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ABOUT THIS MANUAL 



This publication is intended for first-time users of the Information 
Management System/Virtual Storage (IMS/VS) . It provides system 
analysts, data base specialists, system programmers, and application 
programmers with the information necessary for the design, installation 
and operation cf their initial applications, using a subset of the data 
base or data base/data communication facilities of IMS/VS. 

The IMS/VS Primer Function comprises five separately orderable 
documents- One is this document (SH20-91U5). The second is the IMS/VS 
££i§§£ Sample Listings (SH20-9 149), containing a complete IMS/VS sample 
application including generation input, source program examples, data 
base sample data and execution output. The third is the IJJS/VS Primer 
3i.SitI 2®IJBil!ill O^erator^s guide -- BTAM (SH20-9146) , containing a 
sample operating guide for the master terminal operator of IMS/VS using 
the Basic Telecommunication Access Method (ETAM) . The fourth is the 
1£S£1S EEiiBJI Sister Terminal O^e^atoris Guide -- VTAM (SH20-91M7), 
containing a sample operating guide for the master terminal operator of 
IMS/VS using the Virtual Telecommunication Access Method (VTAM). The 
fifth is the IMS/VS Primer Bemote Terminal Operator's Guide (SH20-9148), 
containing a sample operating guide for the IMS/VS end-user/terminal 
operator. The manuals are designed to be used together, i.e., the IMS/VS 
Primer and the Operating Guides extensively reference the samples in the 
IMS/VS Primer Sample Listings. 

The primary objective of the IMS/VS Primer Function is to provide the 
first-time user cf IMS/VS a single document containing all of the 
Information the user would ordinarily need to: 

Plan for IMS/VS use 

Design DL/I data bases 

Design, write, and test IMS/VS programs 

Install the IMS/VS program product (57U0-XX2) 

Operate IMS/VS 

Maintain IMS/VS 

The only other IMS/VS publications the user of the subset would normally 
have to refer to are the IMS/VS General Information Manual and the 
I1JS/VS Messages and Codes Inference Manual. 

While the IMS/VS Primer is designed for the new IMS/VS user, it is 
applicable to other customers, such as: 

• The currently installed IMS/VS user who has a continuing training 
requirement, and 

• The currently installed IMS/VS user who is implementing new 
applications for departments having no experience using IMS/VS. 

By using the approach suggested in the IMS/VS Primer, users can avoid 
much of the complexity usually associated with IMS/VS, Many of the 
steps required to install IKS/VS can be shortened, simplified, and/cr 
accomplished in a mere orderly manner. 
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The IMS/VS Primer is not intended to eliminate the need on the part of 
the user for careful planning, close coordination, and guidance by 
experienced systems personnel, detailed study of the application 
requirements, rigorous program testing, proper operating procedures, 
etc. It is, intended to be a learning guide, a source of field-proven 
techniques and advice, a tested sample system, a subset reference 
manual, and an operators guide. By following this manual, users should 
progress quickly and confidently through the steps required for 
implementation of a simple, initial IMS/VS application, 

is£02e_of_the_ Manual 

Each user has the responsibility to assess the applicability of the 
IMS/VS Primer Function to his requirements. If desired, users can ask 
for guidance and counsel from an IBM representative or system engineer. 
The assessment must be made with a full understanding of the scope and 
intention of the IMS/VS Primer Function- 
Only a subset of the full facilities of IMS/VS is addressed- Although 
the subset is rich in function, a customer's application might require 
additional IMS/VS functions. 

If a user requires facilities not included in the subset, he should 
reconsider, if necessary, any recommendations given here. 

Summary of Contents 

This manual is organized intc nine chapters. 

• Chapter 1, "Introduction," introduces the IMS/VS data base and data 
base communication facilities and a sample application used 
throughout the manual. The chapter is divided into a DB facilities 
section and a DC facilities section. It also provides a brief 
overview of our IMS/VS subset. 

• Chapter 2, "Data Base Design," provides the data base specialist and 
system analyst with information and guidelines for data base design. 
This chapter is applicable to both the DB-only user and the DE/DC 
user. 

• Chapter 3, "Data Communication Design," contains a detailed 
description of the IMS/VS data communication facility. It provides 
guidelines for the design and implementation of data communication 
applications using these facilities. This chapter can be 
disregarded by the IE-only user- 

• Chapter 4, "Data Base Processing," guides the application programmer 
in the design, coding and testing of DL/I batch and IMS/VS message 
processing programs. Only the first part of the chapter is 
applicable to the DB-only user. 

• Chapter 5, "Data Base Reorganization/load Processing," describes 
when and how data bases should be reorganized. 

• Chapter 6, "Data Base Recovery," guides the data base specialist and 
operations staff in the inplementaticn of data base recovery 
procedures. 

• Chapter 7, "Installing IMS/VS," guides the system programmer through 
the installation of a subset of IMS/VS data base and data base/data 
communication system. It also addresses the installation of IMS/VS 
in the Systems Network Architecture (SNA) environment. 
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• Chapter 8, "Operations," contains guidelines for the design of 
operating procedures for the IMS/VS online system. It shows how to 
adapt the saiple master terminal and remote terminal operator guides 
to your own environment. This chapter can be disregarded by the 
DB-only user. 

• Chapter 9, "Optimization ," describes how to monitor and optimize a 
running application. 

Every chapter except the second, third and eighth is divided into two 
parts. The first part of each chapter deals with the data base 
management portion of IMS/VS. The second addresses IMS/VS data 
communication. For your convenience, the following table defines those 
parts of this manual of interest to each functional area in your 
organization. 

DATA 
CHAPTER MANAGEMENT 

t 

1. INTRODUCTION • 

2 DB DESIGN 

3. DC DESIGN 

4. DB PROCESSING 

5. DB REORGANIZATION •• •• » ... . ## 

6. DB RECOVERY •« ... ## . », ,,„ 

7. INSTALLATION •• •• •« ««« .. 

8. OPERATION •• • • • ••• «.« 

9. OPTIMIZATION •* ••• ••« « .«« # «. 



• Reader should be familiar with contents. 
• • Reader should know specific parts in detail. 
• • # Reader should have complete detailed knowledge. 



p£ere£uisites 

Eefore using this manual, you should be familiar with the IBM Operating 
System for Virtual Storage (OS/VS1 or OS/VS2). This manual's design is 
such that the new IMS/VS user will need to make few, if any, references 
to other IMS/VS publications, except for the Genera^ Information Manual 
(GH 20- 1260) and Messages ^^ Codes Reference Manual (SH20-9030f7 ~The 
more advanced ust^, however, will find additional information in the 
listed associated publications. 

The reader should be familiar with the information presented in: IMS/VS 
Gene ral Information Manual (GH20-126 0) (especially Chapter 1, 
"Introduction to IMS/VS," and Chapter 4, "System Configuration") . 
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Associated Publications 

The following IMS/VS Publications should be used if you have a need for 
more IMS/VS information beyond the scope of our subset: 

IMSZ^S^Svstejs^AEJBlicaticn^Desian^Guide, SH 20-90 2 5 

IHS^VS_AgElication_£rggrj^min^ SH20-9026 

I H S/V S_ Sys t ein_P logr. a n m i n g_F ef e r e nc e_ Ma n ua 1 , S H2 -9 27 

IMS/VS^O^eratoris^Feference^Manual, SH2 0-9028 

II S/ V S_ 1 i 1 it i es_R e f e r €nce_ Ma n ua 1 , SH 2 -9 2 9 

IHS/I S_M essajge_ For. j a t_ Se r. v ice_ Ose r I§_G uid a , SH20-9053 

Ili/VS^Advanced^Function^f cr_Communications , SH20-905U 

IHSZVS^Installatign.Guide, SH20-9081 

I^SZ^S.Low^Level^Code^Continuitx Check_in_Data__Lan3uage^I_Program 
IiIsiInci"and~ciiration"M§ii3iII SH20-90U7 

Il?S^VS^Frogram_logic_Manual x LY 20 -8069 

I 1?S Z /VS Failure Analysis Structure Tables JFASTJ__for Dumj: Analx§is x 
LY20-8050~" 

IIS^vs_piagnostic_Aids x LY20-806 3 
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WHAT IS IMS/VS? 

IMS/VS is an IBM program product developed to improve the computer 
user»s ability to implement data base/data communication (DB/DC) 
applications- It relies on and extends the facilities and functions of 
Operating System/Virtual Storage (OS/VS) into the DB/DC environment. 
IMS/VS also makes these data base applications, to a large extent, 
hardware and software independent. 

IMS/VS may be installed in either cf two ways: 

• A data base management system for batch-only operations 

• A data base/data communication system fcr concurrent online and 
batch operation 

This manual addresses a subset of both versions. It covers the 
installation and use of the data base system, the data base/data 
communication system, and the migration of the data base system to the 
data base/data communication system. 

The data base management facility of IMS/VS is also referred to as the 
Data Language/I facility or DL/I. The functions supported by DI/I are 
data base definition, creation, access and maintenance. The data base 
capabilities of EL/I can be used in either the IMS/VS data base system 
(IMS/VS DB) , or the IMS/VS data base/data communication system (IMS/VS 
CB/DC) . 

mX-EATJLBASJS? 

Traditionally,, data files were designed to serve individual 
applications, such as inventory control, payroll, accounts receivable, 
or purchasing. Each data file was specifically designed for its own 
application and stored separately on tape or on disk. Quite often, the 
data files of different applications contained common data elements- 
This redundant data caused an extra problem for the user because it 
became very difficult to keep it consistent. 

Furthermore, the same data in different files often had different 
formats. This variance in the format of common data meant that 
application programs were tailored to specific data organizations and 
even specific physical devices. When new applications, data management 
technigues, or devices were introduced, the application programs 
normally had to be changed. As a result, application programs were 
often in an almost perpetual state of change adding appreciably to the 
overall cost of data processing. 

These undesirable attributes cf data files have been largely eliminated 
by the use of the "data_bas,e. M A data_base is a collection of 
interrelated data elements processable by one or more applications. 

A data base provides fcr the integration, sharing, and control of common 
data. As an example, a manufacturing/distribution company may first 
integrate the data for an application dealing with parts control and 
purchase orders (Figure 1-1)- Subseguently, application data for 
customer order processing and accounts receivable may be integrated. 
The data and the programs of already implemented applications need not 
change when the data of subseguent applications is integrated. 
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Figure 1-1. Application Data Integration -- Data Base Concepts 

A data base provides flexibility of data organization- It allows the 
addition of data to an existing data base without modification of 
existing application programs. In Figure 1-1, the accounts receivable 
data may be added, when it is ready to be integrated, to the parts and 
orders data base. This independence is achieved by avoiding the direct 
association between the application program and the physical storage of 
data. 

Thus, the advantages of a data base are: 

• Control of data redundancy and reduction of resulting duplicate 
maintenance. 

• Consistency through the use of the same data by all parts of the 
company. 

• Application program independence from physical storage organizations 
and access methods. 

• Reduction in overall application costs. 

• Data designs usable for both batch and online processing. 

• A system-provided focal point for the control of data. 

22!-SAMPLE_EMVIRQNMENT 

IMS/VS is not itself an application. It is a framework within which to 
construct data base/data communication applications. To make this 
manual more usable, we will define a sample application. This sample 
will then be used throughout this manual as a base for all the examples. 
It will be used to guide you in a natural way throughout all the 
subseguent steps for a successful implementation of an application using 
IMS/VS. 

The sample application chosen is Parts Control and Order Processing, in 
even more general terms, it could be called "ITEM control and 
TRANSACTION processing," where the "ITEM" could be a part, an account, a 
citizen, or a policy. The "TRANSACTION" could be an order, an invoice, 
a customer inguiry, etc. The fact that we will use this particular 
application in the manual does not preclude the use of IMS/VS for other 



1. 2 IMS/VS Primer 



applications. On the contrary, the basic data structure and processing 
shown in this sample are easy to adjust to other applications. 

00E SAMPLE COMPANY* S REQUIREMENTS 

The sample uses a fictitious company that offers a wide variety of 
building, construction, and engineering parts and materials. The parts 
and materials are purchased frcm manufacturers and sold to customers. 
Most customer orders arrive by telephone. Due to the growth in numbers 
of orders and varieties of items, an upgrade of the existing parts 
control and customer order applications was deemed necessary.. It was 
decided to build a new system which integrated these applications. 

Some objectives for the new application system were: 

• Implement the system in the following order: 

1. Parts control with its associated purchase order processing 

2. Customer order processing 

• Provide central control of parts, purchase orders, and customer 
orders 

• Provide accurate status information on parts in stock, on order, and 
delivered 

• Provide accurate entry of both purchase and customer orders, with 
respect to parts in stock. 

• Provide an interface with the existing accounts receivable 
application, which currently maintains the central customer file- 
This application and its files will net be converted at this stage. 

• Provide a base for the online processing of orders and inquiries at 
a later stage. 

The implementation of the above system will be the common thread 
throughout the examples used in the manual. We will distinguish three 
major inp lementation phases: 

1. The Parts Control application, consisting of a central Parts data 
base and Inventory Report and Purchase Order programs. 

2. The Customer Order application which reguires an additional Customer 
Orders data base, to be integrated with the existing Parts data 
base. A Customer Order program is added. 

3. Addition of requirements to the Purchase Order program. 

In the manual, the three steps above coincide with the three basic 
functional expansions of a typical DL/I environment. We shall refer to 
those as phases. 

Note: Phase 1 should be studied and exercised first. Phases 2 and 3 
are somewhat independent. The actual data base design of your 
application could well be initiated on either the phase 2 or the phase 3 
functional level. 

For each level, we will consider: 

• Data base creation 

• Data base processing 
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• Data base reorganization 

• Data base recovery 

We will also consider the migration aspects of moving from one level to 
the next. 

THE PHASE 1 ENVIRONMENT 

Phase 1 of our sample limits itself to the Parts Control application. 

lh§_£§l£s_Data_Base 

Information about parts is managed by the inventory control department. 
All data will be stored in a Parts data base. 

It consists of one record for each part, which the company stocks. 
Within the record we can identify: 

• Standard information for the part. 

• Stock information for each part. 

• Purchase information for each part. 

The_Parts_Inventory_R everts 

The Parts Inventory Report program provides information about stock 
delivery and order position of each part the company stocks. 

EMIchase_Crder_Frocessina 

The Purchase Crder program handles the purchase orders issued by the 
purchasing department. It checks the input, and prints, changes, and 
deletes orders. 

A more detailed description cf the phase 1 data base and application can 
be found in Chapter 2, "Data Base Design," under the topic: "Sample Data 
Base Requirements for Phase 1." 

THE PHASE 2 ENVIRONMENT 

Phase 2 of our sample environment considers the addition of a Customer 
Orders data base and its associated order processing programs. 

The Customer Orders Data Base 

Information about customer orders is managed by the sales department. 
All order data will be stored in a Customer Orders data base« It 
consists of one record for each customer crder. Within the record we 
can identify: 

• Standard information for this order and customer. 

• Crder detail information for each ordered part. 

• Shipment information for this order. 



1.4 IMS/VS Primer 



A link is required with the parts data base because it is necessary to 
know which parts are on order by each customer and which customer 
ordered a given part. 

fJl§*2MI_0r£er_Processing 

The Customer Orders program inserts, changes and deletes customer orders 
in the Customer Orders data base. It also checks and updates the part 
stock information before the order is accepted. This is planned for 
online processing in the sales department in the near future. 

This application also needs access to the already existing central 
customer file. This central customer file is a key sequenced data set 
(KSDS) under the Virtual Storage Access Method (VSAM) of OS/vs. 

THE PHASE 3 ENVIRONMENT 

In phase 3 we consider a change in purchase order processing. The 
additional requirement is to provide direct access to individual 
purchase orders, both by part number and by purchase order number. 

THE_JMS/VS_D!TA_EASJ_SYSTEM 

The IMS/VS data base system contains three major components: 

• A system definition facility tc allow tailoring of the system to a 
particular OS/VS environment. 

• The DL/I facility through which users meet the data requirements of 
their own applications. 

• Utility programs which assist in the reorganization and recovery of 
data bases, and monitoring cf data base usage. 

In the following we will introduce these components and their functions 
which are of interest to the first -time user. 

SYSTEM DEFINITION 

Eased on user specifications and type of operating system, IMS/VS system 
definition creates a library with DL/I processing modules, a procedure 
library and some modules for inclusion in the operating system. «e will 
cover this process in Chapter 7, "Installing IMS/VS." 

DATA LANGUAGE/I FACILITY 

J0L^J-£2Hce£ts 

DL/I allows application programs tc be independent of access methods, 
physical storage organizations, and characteristics of the devices on 
which the application data is stored. This independence is provided by 
a common symbolic program linkage and by data base descriptions external 
to the application programs. The section entitled "Data Base User 
Interface" defines this interface. 

The majority of the data utilized by any company has many 
interrelationships that can cause significant redundant storage of data 
when conventional organizations and access methods are used. The 
storage organizations and access methods of DL/I make it possible to 
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integrate data and control the amount of data redundancy. Processing of 
data in more than cne sequence can be achieved. All data need not be 
placed in a single common data base. EL/I allows you to physically 
store the data in mere than one data base while maintaining centralized 
ccntrol over all the data. 

The concept of data sensitivity allows you to control the use of the 
data base by each application program. Each program can be limited to 
(that is, be sensitive to) a predetermined subset of the data. This 
further enhances data independence. In addition, any application 
program can be restricted to making only specified types of data base 
requests against the data to which it is sensitive. 

Inj?ircnjent_Definitions 

Within the DL/I environment, the following definitions apply: 

• Segment. A data element of defined length, containing one or more 
related data fields. It is the basic unit of data transfer between 
the application program and DL/I. 

• A 2i/I <l§i§ k§se record. A set of related segment occurrences of 
one or more segment types. Each segment type may have a unique 

f ormat- 

• A CL^I data base. The najor unit of DL/I data storage. A set of 
data Ease records stcred using one of the DL/I organizations and 
accessible by cne or more of the DL/I access methods. A data base 
is typically composed of one or more common OS/VS or virtual storage 
access method (VSAM) datasets. DL/I relates its data base records 
and data bases to a physical storage organization and access method. 

2§£§_l2£§E§£d§nce 

DL/I's data base concept allows user's data and programs to be 
independent of the access methods and storage organizations chosen by 
the data base designer. 

The application program interface to the data in the data base is a 
common symbolic language. In fact, the application program is unaware 
of the particular storage organization, storage device, and access 
method chosen for any data base. Nor is the program aware of any 
pointers which might be used in the physical storage organization. 

£EElication_Data_Structures 

Application programs written to use DL/I deal with amplication data 
structures. This refers to the manner in which the application program 
"sees" the data. A DL/I application data structure consists of cne or 
mere hierarchical data structures programs written to process these data 
structures can be independent of the Efeisical £<*£§ §lEJictur.e. Ihl§ical 
refers to the manner in which the data is stored on a direct access 
storage device. A EL/I application program never deals directly with a 
physical data structure. 

The traditional manner cf representing data can be seen in Figure 1-2. 
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Figure 1-2. Traditional Record Layout 

This picture describes: 
1. 



2. 



The physical structure of the record as it appears on tape or a 
direct access storage device. 

The logical structure for the application. Notice there is no 
difference between the physical (as stored) and logical (as used) 
data structure. 



Each of the three divisions (PART, STOCK, CEDEE) usually contains 
several data elements, or fields. For example, one of the data elements 
in STOCK might be stock location. In addition, the record might 
actually contain multiple STOCK and ORDEE divisions for a single EAST. 

This same record appears in Figure 1-3 as a DL/I logical data structure. 
The PART, STOCK, and CFDEE divisions are now considered segments of 
data. Each segment is made up of several fields. Stock location is a 
field within the STOCK segment. 

The logical data structure in Figure 1-3 is called a hierarchical data 
structure. 



PART 



STOCK 



ORDER 



Figure 1-3. Hierarchical Data Structure 



Hierarchical_Eata_ Structure 

The hierarchical data structure in Figure 1-3 describes the data as seen 
by the application program. It dees not represent the physical storage 
of the data. The physical storage is of no concern to the application 
program. 

The basic building element of a hierarchical data structure is the 
£§£§£t/child relationship between segments of data. See Figure 1-4« 
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Figure 1-U. The Parent/Child Relationship of DI/I 



Each occurrence (or instance) of a £ai§£* §§3S!iIll has associated with it 
0, 1, 2, or mere occurrences of a child segment. Each child segment 
occurrence has associated with it one occurrence of a parent segment. 

Sometimes it is necessary to distinguish between a segjnent tyj>e, that 
is, the kind of segment, and the segment occurrence, that is, particular 
instance of its contents and location. 



AS 
A 



s shown in Figure 1-3, a parent can have several child segment types. 

lso, a child segment can, at the same time, be a parent segment, that 
is, have children itself. The segment with no parent segment, that is, 
the one at the top, is called the root segment. 

All the parent/child occurrences, for a given root segment, are grouped 
together in a DL/I data base record. The collection of all these like 
data base records is a CL/I data base. 

Figure 1-5 shows these relations between the segment, the data base 
record, and the data fcase. 



LEVEL 1 



PART 



LEVEL 2: 



Zl 



ROOT SEGMENT 
one occurrence per 
per data base 
record 



STOCK 



<£. 



ORDER 



LEVEL 3: 



^L 



DEPENDENT SEGMENTS 
0-n occurrences for 
each segment type 
per parent occurrence 



DETAIL 



LEVEL 15: Up to 15 levels of dependent segments 

Figure 1-5. Relations between Segment, Data Base Record, 
and Data Ease 
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Only one segment can appear at the first level in the hierarchy, but 
multiple segments can appear at lower levels in the hierarchy. For 
example, multiple STOCK and CRDER segments can exist for one PART 
segment. Since each dependent segment in the hierarchy has only one 
£§Ll§£l» °r immediate superior segment, the hierarchical data structure 
is sometimes called a tree structure. Each branch of the tree is called 
a hi§E§Echical^path. A hierarchical path to a segment contains ail 
consecutive segments from the top of the structure down to that segment. 

In Figure 1-5, each PART segment with its dependent STOCK, ORDER, and 
DETAIL segments constitutes a data base record. The collection of all 
these records for all FARTs is called a Iita_base, that is, the PARTS 
data base. 

Through the concept of program sensitivity, DL/I allows a program to be 
restricted to "seeing" only those segments of information that are 
relevant to the processing teing performed. For example, an inventory 
program could be written to see only the PART and STOCK segments of the 
data base record shown in Figure 1-5. The program need not be aware of 
the existence of the ORDER segment. 

DL/I allows a wide variety of data structures. The maximum number of 
different segment types is 255 per hierarchical data structure. A 
maximum of 15 segment levels can be defined in a hierarchical data 
structure. There is no restriction on the number of occurrences of each 
segment type, except as imposed by physical access method limits. 

Easic Segment Types In A Hierarchical Data Structure 

Following is a detailed description of the several segment types and 
their interrelaticns within a hierarchical data structure. Figure 1-6 
should be referred to when reading this description. 

• The segment on top of the structure is the root segment. Each root 
segment normally has a key field which serves as the unigue 
identifier of that root segment, and as such, of that particular 
data base record (for example, the part number) . 

• A dependent segment relies on some higher-level segment for its full 
meaning and identification. 

• A 2S£ent/child relationship exists between a segment and its 
immediate dependents. 

• Different occurrences of a particular segment type under the same 
parent segment are twin segments. 

• Segment occurrences of different types under the same parent are 
sibling segments. 

§®9JJ§J2 c -§_Ei§14§_§2£_.£ c -£i!i§§_.l££!i§ 

To identify and to provide access to a particular data base record and 
its segments, DL/I uses sequence fields. Each segment normally has one 
field denoted as the sequence field. The sequence fields in our subset 
should be unique in value for each occurrence of a segment type below 
its parent occurrence. However, not every segment type need have a 
sequence field defined. Particularly important is the sequence field 
for the root segment, since it serves as the identification for the data 
base record. Normally, DI/I provides a fast, direct access path to the 
root segment of the data base record based on this sequence field. This 
direct access is extended to lower level segments if the sequence fields 
of the segments along the hierarchical path are specified, too- 
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Note: The sequence field is often referred to as the key.fieid, or 
sinply, the key.. 

figure 1-6 shows, as a dotted line, an example of an access path. It 
must always start with the root segment. This is the access path as 
used by DL/I. The application program, however, can directly request a 
particular DETAIL segment of a given ORDER of a given PART in one single 
DL/I request, fcy specifying a sequence field value for each of the three 
segment levels. 
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Figure 1-6, Segment Types and Their Relations in a Hierarchical 
Eata Structure. 

Logical Relationships 

In addition to the basic DL/I facilities discussed so far, DL/I provides 
a facility to interrelate segments from different hierarchies. In doing 
so, new hierarchical structures are defined which provide additional 
access capabilities to the segments involved. These segments can belong 
to the same data base or to different data bases. A new data base can 
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be defined called a logical data base. This logical data base allows 
presentation of a new hierarchical structure to the application program. 
Notice that although the connected physical data bases could constitute 
a SJlS2lJS Js£! str.uctur.e, the application data structure still consists 
cf one or more hierarchical data structures. This again extends the 
data independence concept. 

The basic mechanism used tc build a logical relation is to specify a 
dependent segment as a 2oa.ic.al child, by relating it to a second parent, 
the logical cajent. 

In Figure 1-7, the logical child segment DETAIL exists only once, yet 
participates in two hierarchical structures. It has a £hy_sical parent, 
ORDER, and a logical p,ar.ent, PART. The data in the logical child 
segment and in its dependents, if any, are called intersection data. 
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Figure 1-7. Two Logically Related Data Bases, PARTS and ORDERS 

Ey defining two additional logical data bases, two new logical data 
structures shown in Figure 1-6 can be made available for application 
program processing, even within one single program. 



Introduction 



1. 11 



ORDER 



;fc 



DETAIL 



PART 



SHIPMENT 



STOCK 





PART 








"■ ' 




















{S 




s 




S 


** 


s 


STOCK 




DETAIL 


ORDER 


s 




















S 


> 








SHIPMENT 


s 





A. New logical data structure ORDERPART 



B. New logical data structure PARTORDER 



Figure 1-8. The Logical Data Bases After Relating PARTS 
and ORDER Data Bases. 
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RT segment in Figure 1-8 A, is a concatenated segment. It 
he logical child segment plus the logical parent segment. 
DEE segment in Figure 1-8E is also a concatenated segment, 
ts of the logical child segment plus the physical parent 
ical children with the same logical parent are called 
, for example, all DETAIL segments for a given PART 
can be seen in Figure 1-7, the logical child has two access 
ia its physical parent, the £h.ysical access p.ath, and one 
al parent, the logical access ga£h. Both access paths are 
DL/I and can be concurrently available to one program. 



Because the DL/I logical relationship function may not be reguired for 
your first IMS/VS application we will deal with it separately in this 
manual. To show the use of the DL/I logical relationship function we 
will use the phase 2 sample environment. 
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Figure 1-9. A Data Base and Its Secondary Index. 



The segments involved in a secondary index are depicted in Figure 1-9: 

• The index sour.ce secjjnent contains the scurce field (s) on which the 
index is constructed, for example, ORDER*. 

• The index pointer segment is the segment in the index data tase that 
points to the index target segment. The index pointer segments are 
ordered and accessed based on the f ield (s) contents of the index 
source segment, for example, the order number. This is the 
secondary. ££ocessing sequence cf the indexed PARTS data base. There 
is, in general, one index pointer segment for each index source 
segment, but multiple index pointer segments can point to the same 
index target segment. 

• The index tarjget segment is the segment which becomes initially 
accessible via the secondary index. It is in the same hierarchical 
record as the index source segment and is pointed to by the index 
pointer segm€nt in the index data base. Quite often, but not 
necessarily, it is the root segment. 

• The index source and index target segment may be the same, .cr the 
index source segment may be a dependent of the index target segment 
as shown in Figure 1-9. 

In our subset we will always choose the root segment as the target 
segment. With this approach, it is (for the application program) as if 
the index search field replaces the original root keyfield. At the same 
time, however, the original structure is still available to the same 
application program. 

Eecause you might not need the secondary index function of DL/I, we 
separate its discussion throughout the manual. The use of this function 
is shewn in the phase 3 sample environment. 

DATA BASE DEFINITION 

The data base definition language of DL/I provides two levels of data 
base definitions. Both are generated and. maintained independently of 
your application program (s) , thus providing the basis for data 
independence. 
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2§ta_Base_EescriEtion 

The first level is the data base description (EBE) • Each data base 
description is created frcm statements vou provide. The statements 
define the hierarchical data structure and physical organization of the 
data base. These statements are input to a DL/I utility program. The 
output of the utility program is a data base description. It is stored 
in a DBD library. This data base description provides Bl/I with the 
mapping from the application data structure of the data base used in the 
application program to the physical organization of the data used by the 
operating system data management access methods. The data structure can 
be remapped into a different physical organization without program 
modification. Cther application data can also be added to this data 
base and net reguire a change to the original application programs. The 
concept of the data base description reduces application program 
maintenance caused ty charges in the data requirements of the 
application. There are three types of DEDs: 

• The Ehy.sical DEE provides the definition of a single hierarchical 
structure. It car. be used, in this form, by application programs- 
If logical relationships exist, the physical EBE contains a 
definition of those relationships with the other hierarchical 
structure. These relationships can be within the same EBE or with 
another DEE. Multiple logical relationships can exist within a 
single physical DBD. 

• The logical DBE provides the redefinition of two or more related 
hierarchical structures into a new hierarchical structure. These 
hierarchical structures can be from the same EBE or from different 
EEEs. The logical DBD relies on the logical relationships which 
were defined in the physical DEB(s). 

• The secondary index EEE allows definition of a secondary access path 
into a physical or logical EBE. 

The process of generating a DBD is referred to as data base descrip_tion 

S§I ! £ r .§ii°JG (EEEGEN) . 

The second level of data base definition defines the application data 
structure for each application program. 

A £I22£§L51-.s£ecif ication_blocjc (FSB) is created from statements you 
provide for each of your application programs. It defines the 
application data structure required by that application program. A PSB 
contains one or more £rcqran_communica tign_blgcjcs (PCBs) , one for each 
hierarchical data structure the program intends to use. Each PCE 
defines the hierarchical |sub) structure the program "sees" from the 
physical or logical data base. It specifies for each segment the kinds 
of access allowed by the program, that is, read only, update, insert, 
and/or delete. The PSB is created, like the DBD, by a DL/I utility 
program. It is stored in a PSB library. The process of generating a 
PSE is referred to as program sgecif ication block generation (PSBGEN) . 

APPLICATION EECGFAM INTEFFACE 

IMS/VS provides a common data manipulation language, called the EL/I 
i§H2!i.§ge Interface, for the application program. Through this 
interface, the application program can reguest that DL/I: 

• Petrieve a unique segment (GET UNIQUE) 

• Retrieve the next sequential segment (GET NEXT) 
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• Replace the data in an existing segment (REPLACE) 

• Delete an existing segment (DELETE) 

• Insert a new segment (INSERT) 

Such a request is often referred to as a DL/I cal.1 or call. A DI/I call 
may deal with one or more segments in a hierarchical path. Segment 
retrieval is based upor either cr bcth of the following: 

• Position in the data base, as set by previous calls 

• Comparisons between fields within the segments in the specified 
path, and values supplied with the DL/I call. 

The IMS/VS data manipulation language can be used in COBOL, PL/I or 
Assembler language programs. Ihe data manipulation language is 
independent of data base organization and access methods. Only a small 
interface module is link edited to your application program. 

LOGGING ANE CHECKP0IN1/R ES1ART FACILITY 

DL/I provides a logging facility. If selected, images of data in the 
data base before and after mcdif ication are written to a system log data 
set. This log data set, together with a previously made image copy of 
the data base, can be used for data base reconstruction should an 
application or system failure occur. You may also include DL/I 
checkpoint calls in your batch application programs. This enables you 
to restart a job from the last checkpoint in the event of program or 
system failure. 

DATA SECURITY 

IMS/VS DB provides two mechanisms for data security. The first is the 
program specification block which controls the data base access of each 
application program at the segment level. For maximum benefit of this 
security provision, the library containing the PSEs should be password 
protected. 

The second mechanism is the extended security support of IMS/VS which 
provides an interface between IMS/VS and the Resource Access Control 
Facility (RACF) program product in the 0S/VS2 MVS environment. This 
extended security support is not included in our subset. For more 
information you should refer to the IMS/VS General Information Manual 
and the IMS/VS System/ApElicaticn Design Guide. 

UTILITY FBCGFAMS 

The IMS/VS DB system includes a comprehensive set of utilities. These 
utilities are used in our subset to: 

• Implement logical relationships and/or secondary indexes at initial 
load time of the data base (s) • 

• Recover data bases in the event of program or system failure. 
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• Reorganize data bases, if needed, to: 

Optimize direct access storage. 

Change the storage organization or access method. 

Change logical/physical data structure. 

• Monitor the performance of programs to aid in optimization. 

IMS/VS BATCH SYSTEM FLOW 

The Data Language/I facility of IMS/VS is used in a batch-only data base 
environment as shewn in Figure 1-10. 
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Figure 1-10. IMS/VS Batch Processing Region System Flow 
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The following notes relate to the circled numbers in Figure 1-10: 

1. The IMS/VS batch control program is invoked by OS/VS task 
management. It supervises the loading of required IMS/VS modules 
and initializes the batch operating environment. 

2. It links to your batch application program, vhich has been 
link-edited with the language interface. 

3. When your application program issues a EL/I call, control is passed 
via the language, interface to the program request handler. The 
program request handler provides preliminary checking of the call 
parameters, and passes control to the Dl/I call analyzer. 

4. Depending on the function requested, the DL/I call analyzer passes 
control to the appropriate call processor module. The DL/I action 
modules request services from the OS/VS data management access 
method modules and log their activity on the IMS/VS log. 

5. Optionally your program can request a checkpoint to establish a 
restart point. Checkpoints are logged en the IMS/VS log to enable 
restart if reguired. 

6. When your application program finishes processing, it returns 
control to the batch control program for termination processing. 

Note: In the IMS/VS EB system, a data base can be accessed, for update, 
by only one application program (one partition/region) at a time. 

£!Ti_EASJ_fiEMINISIBAlIQN 

The centralization of data and control of access to this data is 
inherent tc a data base management system. One of the advantages of 
this centralization is the availability of consistent data to more than 
one application. As a consequence this dictates a tighter control of 
that data and its usage. Responsibility for an accurate implementation 
of control lies with the Eata Ease Administration (EEA) function. 
Because the actual inplementaticn of the EEA function is largely 
dependent on a company^ organization, we limit ourselves to a 
discussion of the characteristics of a EBA. Quite often, the DBA 
function at new IMS/VS installations is performed by an individual or 
group with experience in both application and system programming. 

TBA CHABACTEBISTICS 

• The DBA provides standards for, and controls the administration of, 
the data bases and their use. 

• The EBA provides guidance, review, and approval of data base design. 

• The EBA determines the rules of access to the data bases and 
monitors their security. 

• The EBA controls the data base integrity and availability, 
monitoring the necessary activities for reorganization and 
back-up/recovery. 

• The EBA is net responsible fcr the actual contents of the data 
bases. This is a responsibility of the user. Bat the DEA enforces 
procedures for accurate, complete, and timely updates of the data 
bases. 
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« The DEA approves the operation of new programs with existing 

production data bases, based on results of testing with test data 
bases. 

• The DEA is responsible for the maintenance of current information 
about the data in the data base. Initially, this responsibility 
might be carried out using a manual approach. But it can be 
expected to grow to a scope and complexity sufficient to justify, or 
even necessitate, the use cf a data dictionary program. 

NAMING CONVENTIONS 

Good naming conventions are mandatory in a data processing project, 
especially, in a multi-application environment. They are a prereguisite 
for the eventual iiplementaticE of a data directory, or dictionary, 
system. In the following section we will propose a naming convention as 
an example, and we will use it in all the samples in this manual. You 
might adapt this convention to your own specific environment. In doing 
so, you should consider the following guidelines: 

• Each entity should have a unique name. 

• Each name should contain an entity classification. 

• Each name should contain a system, application or project 
identification. 

• Each name should contain a version identification. 

Naming_Convention_For_Entities 

All entity names to be used in our sample will be coded: tsvnmmmm 
where: 

t = type identifier: 
E is DED 

P is PSB and/cr Program 
S is Segment 
f is Field 
D is DDname 
T is Transaction 

s = system, application or project identifier. In all 
samples the following are used: 

E is an example 

is of general use 

v = version number. In samples the following codes 
are used: 

if of general use 

1 if used in phase 1 and later 

2 if used in phase 2 and later 

3 if used in phase 3 and later 

mmmmm = mnemonic (user's choice) 

Note: The online IBS/VS system requires the program and PSB name to be 
the same. Therefore, the programs are renamed during linkage-editing on 
the sample jot. 
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Sam£le_Job_Names 

The sample jobs referenced in this manual and listed in the "IKS/VS 
Primer Sample Listings*, have the following naming convention: 

• //SAMPInn for the IMS/VS installation jobs, if OS/VS1- 

• //SMVSInn for the IMS/VS installation jobs, if 0S/VS2 {MVS) .. 

• //SAMPnnn for the sample application jobs. 

§AKPLJ DISTRIBUTION ANf LIllIfiGS. 

The samples referenced in this lanual are distributed as part of IMS/VS. 
After IMS/VS installation, as described in Chapter 7, "Installing 
IMS/VS," two sample libraries are available: 

• IMSVS.PRIMESRC, which contains all the sample programs, DEEs, ESEs, 
data base input data, etc. 

• IMSVS.FRIMEJCE, which contains all the sample jobs to install IMS/VS 
and exercise the sairfle programs and procedures. 

For your convenience, both sample libraries are listed in the "IKS/VS 
Priner Sample Listings" publication, together with selected sample jcb 
output. 

THI_PBCJJCT_1PJPR0JCH 

The implementation of IMS/VS-based applications is most successfully 
done with a project approach, With this approach, you assure that 
adeguate planning is dene in a tieely manner, stating all the necessary 
steps for the design, test, and installation of the application. For 
more complex applications, a project team with a definition of the tasks 
and responsibilities of all parties involved is recommended. 

5HI-25QJIQT_cycl| 

Like most other data processing projects, an IMS/VS project can 
generally be divided into the following phases: preliminary 
investigation, planning, design and implementation, testing, and 
operation and maintenance. Figure 1-11 shows the relative manpower 
requirements for each of the phases. 
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Figure 1-11, The Project Cycle 

Following is a brief introduction to each of the phases: 

The_Idea: Normally, a user requirement or a management decision is the 
initial starting point of the project. 

2££iiliB!.IX_Ili aestivation: This phase concentrates on the definition of 
the objectives. A^feasibility study, with a preliminary cost/benefit 
analysis, is conducted. 

PilJQ£i£ii* & project plan is established. A project team is formed, and 
the tasks and responsibilities of individuals and departments are 
defined. A budget is established for the project, and resources are 
allocated. Approval for the implementation is obtained. A change 
ccntrol procedure is implemented to control modifications during 
implementation. 

£esi£n_and_Im£lementation: The system is designed, and that design is 
reviewed. After design approval, detail designs are worked out and 
approved, coding is done, and a test plan is created. 

Test: Eoth unit tests and integrated system tests are performed. These 
are"~followed by an acceptance test. 

O^erat ion^_and_Kaintenance: Production use of the system- is started. Any 
further changes to the system are controlled via maintenance procedures. 

Another important aspect is project administration. The timely and 
accurate planning for and establishing of standards and guidelines is 
mandatory for an efficient project implementation and later maintenance. 
Most organizations already have standards which should be extended into 
the data base environment. At a minimum, standards should be available 
for: 

• Naming of data base items such as DBDs, PSBs, segments, and fields. 

• Documentation of data structures, programs, and procedures 
(production, reorganization, recovery). 

• Administration of data sets, data bases, back-up copies and leg 
tapes and their interrelationships. 

All of this should be under the control of a data base administration 
(DBA) function- 
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SAMPLE PBOJECT PLAN FOB IHS/VS DB 



The following sample project plan should be adapted to your specific 
environment. Typical additional activities might be data clean-up, and 
conversion of existing programs and data. 

Figure 1-12 shows a gross FEBT chart for the implementation of an IMS/VS 
DB project. The necessary system-oriented activities, such as hardware 
and operating system installation, and system maintenance, are not 
included since these are largely dependent upon the installation 
environment. The following descriptions apply to the activities shewn 
in ths PEBT chart |Figure 1-12). 
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Figure 1-12. IMS/VS-DE Installation Plan PEBT Chart. 



Sl§tem_Pianning_J000;:i001: The sample PEBT chart is adapted to your 
project. Manpower'andTmachine time estimates are compiled. External 
interfaces are defined. Elapsed time calculations are performed, and 
the chart is extended with the proper timefram. The critical path is 
calculated. A Gaj}£t_char.t can be constructed showing the duration and 
people involved for each activity. Figure 1-13 contains an example of 
such a Gantt chart. The Gantt chart should clearly state the actual 
days/months to bs spent by each individual. 

§Istem_Des.i2n_JJC02ii)£ls The overall system design is made. All 
components and their interfaces are defined. The user interface is 
detailed and reviewed for acceptance. 

J5§X®iSEa^at-5i§S-J2&Srl201: A detailed plan for the development of data 
bases and programs is devised. All single activities and their 
dependencies are determined. 
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l£ucation_J100;390;590;;Z()01: Together with the development plan, the 
iducation~of~ali parties Involved should be arranged. 



ACTIVITY 



EDUCATION 
IMS/VS INTRODUCTION 

IMS/VS-DB FOR 
FIRST-TIME USERS 

DEVELOPMENT 
SYSTEM DESIGN 

DB GROSS DESIGN 

DB DETAIL DESIGN 
(DBOs AND PSBs) 

PROGRAM DESIGN 
PGM CODE AND TEST 



INSTALLATION 
INSTALL IMS/VS-DB 

RUN SAMPLE 
SYSTEM TEST 



TIME 



I 



few::*:* : * ! 



^^ 



mm 



zzzz 



mz® 






HHH 



ALL 



^/^ SYSTEM ANALYST 



ligljlj DATA BASE SPECIALIST 

t=j SYSTEM PROGRAMMER 
I"! OPERATIONS STAFF 



PRODUCTION 



Figure 1-13- Sample Gautt Chart. 



5§i§_l§§§_5l2§§-2§§i23_JlQ0-430l: An overall data base design, 
specifying the logical data structures and the basic physical 
implementation, is created. 

II2SI§I_J2§sign_J30.£;:Jj2Cl: The individual programs are defined and their 
input, processing, output and data base accesses are defined. Common 
guidelines and routines are established. Often more than 50% of the 
data base processing programs are reports. Using COBOL or EI/I report 
writer features or a report writer/query language such as GIS/VS can 
help to minimize the manpower reguired fcr program design. 
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Cgllect.Data^JlOO-aiO^SOOj. 30 0-560-6601: Eoth test data and live data 
are collected, or procedures/programs are established for the conversion 
of existing data files. 

^£92^Ll-^H^^±9I^LiZ^%k^^ll^zH!i^Z^^Z^Qzl^Q.i» * timely plan for 
recovering and reorganization can avoid later redesign and 
reprogramming. These procedures, although rarely needed, are vital to 
the data base integrity and availability. Therefore a thorough test 
plan must be made and carried out before production starts. The 
production staff should b€ carefully trained in problem determination 
and the secure and accurate execution of such procedures. An incomplete 
treatment of this topic is the most common source of problems when 
implementing a data base management system. 

l£stall_IHS/VS_DE_and_Bun_SamEle_J^ The system programmer 

installs the IHS/VS data base system. The sample application provided 
with the system is exercised to get practical experience with the 
system. Conventions and procedures for system maintenance are 
established- 

P§£§_l§§§_P§£§il_£§§i9S IM30-5001: The detailed logical and physical 

data bass structures are defined. Access methods are selected, and the 
DBDs are coded and tested. 

Ilfi2IlS_2il§i2_S£li911_iifi5lJJjSL : Detail flowcharts, decision tables, 
pseudocode, or other design documents, are established for each 
individual program. The data base call sequences are defined in a 
standard fashion. 

Test_Flan_ JU 2 - 6 C Cl : A detail test plan is made. Procedures for unit 
test and system test are established. 

Develop Load Programs and load _ lest Data Eases. (U2Q-500-6QQ) : Load 
program (s) are designed, coded, and tested with the test data, resulting 
in test data bases for program and recovery/reorganization tests,. 

P§§i95_lSli§2_J5_0fil : ^ n€ tasic aim of the design review is to assure 
that the specified requirements are met. Major review topics are: 

« Are the applications really what the users want? 

• Is the performance expectation still valid? 

• Are there any pitfalls in the data base and program design? 

ItoQESi-SS^-ISE^Ccding^and^Test^JSJO-eoO^TOOl: Each individual program 
is coded and tested, using the test data bases and the test procedures. 

L2§£_"Live^_pata_Eases 166027001: The data bases are loaded with actual 

data. This process at times exposes inconsistencies in data. You may 
need to include extra time tc resolve these inconsistencies. Eack-up 
copies are made immediately after initial load to provide a full back 
base for system test. 

Sy s t ejn _Te s t_J 7 Q£z J CjQl ' Integrated tests are executed on the live data 
bases. Reorganization and back-up/recovery procedures are tested on 
those data bases. 

£E§E§£i25_§fi£-32iS£§U§fi£§_J§00-9001: Production use of the system 
starts. lhe~estaElish€d~ionitcring and maintenance procedures are 
enforced. Feed-tack is given tc development for future projects. It is 
strongly recommended that the test environment be maintained in addition 
to the production environment. This will be of benefit for future 
trouble shooting, application modification, and application extensions. 
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1HI JMS^VS DATA COMJONICATICN FEATOEJi 



The IMS/VS Data Communication feature provides a symbolic program 
linkage between data communication terminals and the remainder of 
IMS/VS. This is in addition to the previously discussed Data Language/I 
facility, which is an integral part df the full IMS/VS DB/DC system. 

In our subset we will mainly consider the operation of IMS/VS-DC in the 
Systems Network Ir.cbj.tectur.e (SNA) environment, utilizing the Virtual 
IsficommasAcatiojj Access Method (VIAM) and the Network Control 
!iiii3SJ2![i£iiiT"§£iiIii~ (NCP/VS). However, Chapter 7, "Installing 
IMS/VS7" also covers the use of the Easic Telecommunication Access 
Method (ETAM)» Those net planning to~use VTAM with~IMS/VS should^skip 
to~thi section "IMS/VS Cata Communication Concepts." 

We will similarly limit curselves to the following hardware components: 

• 3705 Local Communications Controller. 

• IBM 3270 Information Display System, local and/or remote (leased 
lines only) • 

Figure 1-14 depicts the relations between these system components. 
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Figure 1-14. IMS/VS in the SNA Environment 

SOME EASIC SNA CONCEPTS 

Systems Network Architecture was designed as an architectual base for 

he development of a data communication network and its components, such 
as: 

Terminal subsystems — IBM 3270 Information Display System 

Line protocols — Synchronous Data Link Control (SDLC) 

Communication controllers -- 3705 

Network control programs -- NCP/VS 

Telecommunication access methods -- VTAM 

SNA formally defines the functional responsibilities of communication 
system components. In an SNA structure, all nodes (linked elements) 
adhere to these definitions. The scope of SNA definitions ranges from 
bit-level message header formats to the protocol of message seguences 
and to the classification of network nodes according to function. 
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S§E3£3£i2S_2!_fy2££i2£s_intc_LC3ical_LaYers 

A key concept of SNA is the division of the communication systeir 
functions into a set of well-defined layers. The major functional 
layers defined by SNA are: 

• Transmission subsystem layer 

• Function management layer 

• Application layer 

SNA is structured into these layers for two basic reasons: 

1. To permit changes to b€ made in one layer without affecting other 
layers- 

2, To allow interactions between functionally paired layers in 
different units. This pairing is required to support the 
distribution function. 

Ii£§_l£§D§5i§§i23_s2j2§y,§£em_ layer: The transmission subsystem is 
concerned with the routing and novement of data units between origins 
and destinations. The transmission subsystem does not examine, use, or 
change the contents of these data units- This separation, where the 
routing of a data unit is independent of the contents of the data unit, 
means that a change in the method of transmission between nodes requires 
no change in the data unit itself. Therefore, the support provided by 
the function management layer can be used across a variety of physical 
connections. 

Paths through the network may be shared by many applications. The paths 
may consist of several physical components with interconnecting data 
links. The transmission subsystem provides the control necessary to 
manage these shared resources. 

5k§_l!iS££i2S_]3§S§S§JB§£t_]:22§£- Th « application layer employs a set of 
requests to invoke the services of the function management (FM) layer. 
The function management layer presents information from one application 
layer tc another application layer. Separation of the function 
management layer from the application layer and from the transmission 
subsystem layer allows device-specific transformations to be distributed 
out of the main processor. 

The_A££licaticn_Layer: The application layer is concerned only with 
application functions. This layer performs the user's application 
processing and need not be involved in the protocol or procedures for 
controlling a communication line or routing data units through the 
network. 

Note: In SNA terminology, the whole of IMS/VS is called one application 
program. This use should net be confused with that pertaining to IMS/VS 
application programs written by the user. 

l£il-2s«Iir*._ll£ d .§j§_§JJd_ Sessions 

End users are the ultimate sources and destinations of information. End 
users include programs (that is, IMS/VS) and operators (that is, 
terminal users) . The structure of SNA allows end users to be 
independent of, and unaffected by, the specific services and facilities 
used for information exchange. End users are represented by nodes. So 
a 3270 display unit is a node. Sc is IMS/VS itself. Notice that a 3705 
Communications Controller is also a node, an intermediate one. To allow 
information exchange between two nodes, these two nodes must be engaged 
in a session. Sessions are generally initiated (logon) and terminated 
(logoff^ by one cf the nodes. 
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The Virtual Telecommunication Access Method (VTAM) is actually the 
implementation of SNA in CS/VS- VTAM manages the activities of a data 
communication system. It allocates resources and manages the flow of 
data between the nodes in the system. To accomplish this, VTAM provides 
the following functions: 

Starting and stopping the network; VTAM enables an installation to 
define the data communication system and some of its characteristics. 
Once the system is defined, VTAM can be started and the system 
initialized. VTAM can alsc be used to shut down the system in an orderly 
fashion. 

S^^fiSiaS-illS-SSfiJiSSraticn^ynamicallj; : VTAM enables the network 
operator at an OS/VS system console to monitor the use of the resources 
within the data ccmnunication system and to alter the network as 
necessary. 

Allocation: VTAM controls the allocation of network resources. By 
owning and controlling all resources, VTAM provides a focal point within 
the system for controlling the network. 

I^C_j:£oce ssi ng : VTAM manages the transmission of data between 
application programs (that is, IMS/VS) and terminals. It enables 
application programs and terminals to communicate with each ether 
independently of how the terminals are connected to the central 
processing unit. VTAM also relies upon the distributed function 
throughout the network (such as in cemmunications controllers and 
programmable terminals) to reduce the processing requirements in the 
central processing unit- 

liiiStiiitX*. 31§i2§.£iii£y.# JifiJ serviceability (RAS) : VTAM offers a 
design and facilities that reduce the incidence of problems in the data 
communication system, reduce the impact of errors that do occur, and 
assist in maintaining the data communication system. 

NCP^VS_and_the_3205_Comnunicaticns_Co 

The Network Control Program/VS active in the 3705 Communications 
Controller, provides the following basic functions: 

• Sending and receiving data to and from VTAM in the central 
processing unit (CPU) via a S/370 channel. 

• Sending and receiving data to and from terminal control units via 
communication lines. Beth binary synchronous communications (ESC) 
and SDLC line disciplines can be used with the 3270 Information 
Display System. 

IMS/VS DATA COMMUNICATION CONCEPTS 

The following sections give an overview of the concepts and facilities 
of our subset of the IKS/VS Data Communication feature. 

i!iy.§i£3i_5§£3iI2§is 

Physical terminals are the hardware devices used to enter or record 
messages being sent or received over communication lines. Within the 
IMS/VS environment, physical terminals may be permanently attached to 
leased communication lines or operate on a switched communication line 
(remote attachment) , or be attached directly to the CPU channel (local 
attachment) • 
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Although IMS/VS supports a wide variety of terninals and terminal 
subsystems, in this manual we Mill only consider the IBM 3270 
Information Display System (also referred to as 3270) attached locally 
or via leased lines.. In addition, we will limit ourselves to the 
following 3270 control units and their attached display and printer 
stations: 

3271 Model 1, 2, 11 or 12 

3272 Model 1 or 2 
327*4 Model 1E or 1C (BSC line protocol only) 

3275 Model 1 or 2 

3276 Model 1, 2, 3 # or U (ESC line protocol only) 

J270 Device Compatibility: The 3270 hardware provides for the display 
of a small size screen foriat en a larger size screen display unit. A 
12xi*0 screen format for a 3277/3275 Model 1 will be displayed in the top 
left part of a 12x80 display unit (a 3276/3278 Model 1 or 11). A 24x80 
screen format (for a 3277/3275/3276/3278 Model 2), will be displayed in 
the top part of a 32x8C display unit (3276/3278 Model 3) or a 43x80 
display unit (a 3276/3278 Kodel 4). 

Lo<jical_ Terminals 

A logical terminal is a name that is related to a physical terminal, 
that is, a node. One physical terminal can have one or more logical 
terminals associated with it- The user of IMS/VS refers to the logical 
terminal in the constructicn and transmission of messages. The user is 
never concerned about such things as physical terminal addresses. If a 
physical terminal becomes inoperative, the logical terminal(s) 
associated with that physical terminal can be dynamically reassigned to 
ancther physical terminal, thereby reassigning output gueues of messages 
to another physical destination. 

J5aste£_Ter.minal 

The master terminal is a logical terminal that acts as the operational 
hub of IMS/VS. The master terminal operator has complete ccntrcl of 
IMS/VS communication facilities, message scheduling, and data base 
operations. This facility is used for checkpointing and restarting the 
system, for continuous monitoring of the system, and for dynamically 
altering the operation of the system. In case of master terminal 
failure, the operating system console can be used as an alternate master 
terminal. Since the master terminal is a logical terminal, it may be 
dynamically reassigned to ancther physical terminal. In our subset, the 
master terminal must be a 3270 display unit with a screen size of 24x80 
(1920 characters) in combination with a 3270 printer- 

Ififiut-^tssages 

IMS/VS processes three basic types of input messages. The first one to 
eight characters of the first message segment determine the message type 
and identify the destination of the message text that follows. 

• If the input message identifier is a transaction code, the message 
is a transaction, and its destination is the application program 
defined to process the transaction. 
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• If the input message starts with the name of a logical terminal, the 
destination is a terminal. This message type is known as a 
terminal-tc-terminal message switch. 

• If the first character of the input message is a slash {/) , the 
message is an IMS/VS command. The command code immediately follows 
the slash, IMS/VS commands are entered by IMS/VS terminal operator 
to direct IMS/VS to display or alter the status of one or more 
IMS/VS system resources. 

Out£Ut_ Messages 

Output messages to IMS/VS terminals originate from application programs 
in response tc terminal input, from IMS/VS itself, or from other 
terminals (message switches) « An application program can send output 
messages to logical terminals ether than the one generating the input 
message. 

J3§ssage_Format_ Service 

IMS/VS provides a comprehensive editing facility for the IBM 3270 
Information Display System and ether terminals. It is called message 
f°.£I§£ service {MFS). 

MFS allows application programs tc deal with logical messages instead of 
device-dependent data, thus simplifying application development. The 
presentation cf data on the device or operator input may be changed 
without application program changes. Full paging capability is provided 
for display devices, thus allowing the application program to output a 
large amount of data to be divided into multiple screens for display on 
a terminal. The terminal operator can page through subsequent screens 
within the message. At the end he can return to the first page cr skip 
to the next output message. Input can be accepted from any screen if so 
defined in MFS format definition statements. 

The basic concept of MFS is that the application designer describes to 
the IMS/VS MFS language utility: 

• The input message format as it will appear from the device 

• The input message format as it is to be presented to IMS/VS and the 
application program 

• The output message format that the program will present to IMS/VS 

• The output message format as it is to appear on the device 

Eased on above descriptions, IMS/VS formats the data coming from the 
device going to the application program, and vice versa. 

Mej3sage_2ueuin<3 

All input and output messages, except command input, are queued in main 
storage, with direct-access storage backup as required. In this way, 
messages can te received by the system although the resources necessary 
to process them might not be immediately available. For improved 
performance, long and shcrt messages are queued on separate 
direct-access data sets- Space in a message queue data set is reused 
when it is no longer required fcr a previous message. 
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Conversational processing lets the user retain message continuity from a 
given terminal even though the program that processes the conversation 
is not retained in main storage throughout that conversation. Whenever 
a transaction code is defined as conversational, the application program 
can interrelate messages from a given terminal using a sc.£a£ch£ad ajrea 
(SPA). A unique SPA is created for each physical terminal from which a 
conversational transaction is entered. 

Typical contents of the scratchpad area are data from the terminal and 
frcn data bases to be saved between interaction passes of the 
conversation. One scratchpad area is used for each terminal operating 
in conversational mode. IMS/VS automatically compresses and expands 
scratchpad contents to reduce data movement and I/C requirements. 

Any subseguent data entry from a terminal already operating in 
conversational mode causes the message processing program processing the 
transaction to receive both the contents of the scratchpad area and the 
input terminal data- Each input message is considered as an individual 
unit of work for the prograi. 

A terminal command is available to enable the terminal operator to end a 
conversation prior to its normal completion. Commands to temporarily 
suspend and save an incomplete conversation, and to resume that 
conversation at a later time are also available to the terminal 
operator. 

Security. 

IMS/VS enforces several types of user-defined security requirements. In 
our subsets, two types of security verification may be designated: 
terminal security and password security. Terminal security ensures that 
a transaction or command may be entered only from specific, designated 
logical and/or physical terminals. Password security ensures that a 
transaction or a command message will not be processed unless a 
user-defined password is appended to the transaction code or to the 
command verb. 

Security violations are recorded en the IMS/VS master terminal and 
system log after a specified threshold count. Access to IMS/VS data 
bases by non-IMS/VS applications or operations must be secured by the 
user's own operational policy and procedural controls. The extended 
security support of IMS/VS provides an interface between IMS/VS and the 
£§J2JJI£ e IsSSJs. Ccntroi facility. (RACF) program product CS/VS2 MVS only 
or a" use rewritten exit. This extended security support is not included 
in our subset. For more information you should refer to the IMS/VS 
General Information Manual and the IMS/VS Sy,stem/Ap.£lication Design 
Gfiide- 

Termiua^Command^anguage 

The IMS/VS terminal command language is used by IMS/VS terminal 
operators to display and alter system resources. The major command 
functions are described belcw. Most commands can be specified to 
operate on one or more occurrences of a particular resource type. Most 
commands for dynamically interrogating or altering the processing 
functions of IMS/VS are limited to the master terminal. The major 
functions available to the master terminal operator through commands 
are: 

• Starting, stepping, or otherwise modifying the system functions of 
message receiving, queuing, scheduling, and sending. 
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• Allowing the IHS/VS system to purge its message queues prior to 
shutdown. 

• Temporarily halting transaction processing , message processing, 
program scheduling and execution, and data base usage. 

• Starting and stepping message processing regions/partitions. 

• Initiating and controlling IHS/VS checkpoints and restarts. 

• Modifying logical terminal to physical terminal assignments. 

• Displaying the status of various resources, such as transaction 
types, programs, data bases, message queues, and communications 
facilities. 

• Displaying main storage buffer pool and control block pool 
utilization. 

The major functions available to the remote terminal operator (nonmaster 
terminal operators) through commands are: 

• Terminating, saving, or releasing a conversation. 

• Sending a message to a selected logical terminal. 

• Formatting a 3270 display screen for data input. 

• Displaying the identification of the master terminal. 

l£§fi§§ction_Fesponse_Mode 

Response mode is an option that causes interactions between the terminal 
operator and the application program to be synchronized. When IMS/VS 
receives an input transaction that causes response mode to be used, 
IMS/VS accepts no mere communication from that terminal until the 
application program response has been transmitted. This will be the 
typical mede of operation in our subset. 

MESSAGE SCHEDULING 

Separate operating system regions or partitions are used for message 
processing. These regions or partitions are initiated through the normal 
operating system job management routines during IMS/VS initialization or 
by an IMS/VS master tertinal command during IMS/VS execution. 

All messages acceptable to the system are predefined and verified 
through a 1- to 8-character code in the first segment of a message. 
When a valid message is completely received and queued, its presence is 
made known to message scheduling. When the required resources for 
message scheduling are available, processing is initiated. 

LOGGING AND CHECKPCINT/EESTABT 

This facility supports logging, checkpointing, shutting down, and 
restarting IMS/VS executions. Ihe online checkpoint and restart 
functions are dependent upon queuing all messages on direct-access 
storage and recording of all messages and data base modifications on the 
system log. 
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Logging 

Id the IMS/VS DB/DC system , all message and data base modifications are 
recorded on a central system log data set. This log data set is 
compatible with the DL/I batch log data sets. The data base changes of 
both types of log data sets can be accumulated into one change 
accumulation data set. This provides a consistent recovery mechanism 
for data bases used in online and batch operations. In our subset, this 
log data set must be on a magnetic tape. 

Checkpoints 

Periodic checkpoints of IHS/VS are used to provide the ability to 
restart after loss of main storage, direct access storage message 
queues, or data bases. The master terminal operator can enter commands 
to take a checkpoint and IMS/VS itself automatically takes a checkpoint 
periodically. The following checkpoints are distinguished: 

• System-scheduled checkpoints based upon log activity. 

• After a master terminal reguest for orderly termination of the 
system. Unprocessed input messages may be retained on direct access 
storage queues or recorded on the IMS/VS system log for subsequent 
processing. 

Restarts 

IMS/VS can be stopped and restarted daily or at explicit intervals. 
Restart reconstructs the system after a controlled stop, an emergency 
stop, or a data base destruction. To start the IMS/VS system, the 
operator instructs the operating system to start IMS/VS. Once the 
IMS/VS control program is operative, one or more jobs, which become 
IMS/VS processing regions/partitions, may be initiated. Remaining 
regions or partitions are used for batch processing. Upon initiation of 
the IMS/VS control program, a message is transmitted to the master 
terminal requesting an indication of the type of restart for IMS/VS. 
The operator's response causes control to pass to the restart facility, 
which optionally reads the old system log. This log contains input 
messages received but not processed, or output messages generated but 
net transmitted, en the previous execution of IMS/VS. 

Any other information required to restart the system is also carried on 
the log. Messages on this log are put back into the same message queues 
in which they were left at the previous system stop. After completion 
of the restart processing, the master terminal operator may enter 
commands to initiate communication line operation, message processing, 
and data base use. 

Restart without a system leg is equivalent to an initial start {cold 
start) for all message transmission and processing. 

When IMS/VS is restarted after an abend, the restart capabilities of 
IMS/VS provide the following information to the master terminal: 

• The name of the message processing program that was executing in 
each message processing address space at the time of abend. 

• The input messages that caused the message processing programs to be 
scheduled. 
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Data base modifications are logged. This information is used at 
restart. The data base modifications caused by programs in process at 
time of failure are automatically backed out and the original input 
messages are reprocessed in their entirety. 

In addition to system restart, facilities are provided to reconstruct 
data bases using image copies and the system leg. 

UTILITY PROGRAMS 

In addition tc the utility programs available with Til/1, the IMS/VS Data 
Communication feature provides several utility programs. The following 
utility programs are introduced in our subset: 

• Application control block maintenance. Uses the output of program 
specification block and data base description generations to create 
and maintain the control blocks in a form directly usable by the 
IMS/VS online system. 

• Security maintenance. Creates control blocks that describe the 
terminal and transaction security reguirements. IMS/VS uses a 
scheme of passwords for terminal and transaction access. 

• System log analysis. deduces statistical reports having usage of 
message types and terminals. 

• MFS language. Creates control blocks that describe message and 
device formats for devices using message format service (MFS) • 

• A DC Monitor report program which provides information regarding the 
performance of the system. This is based on the output collected by 
an optionally activated monitor in IMS/VS. 

• System log recovery and termination programs to recover or terminate 
the system leg in case of machine errors. 

ISS^VS DATA EASE/DATA COMMUNICATION SYJTEM FLOW 

The following three kinds of regions, address spaces, or partitions 
under OS/VS are distinguished in an IMS/VS-DB/DC system. 

• The control (CTT) recjion contains the IMS/VS control program. It 
controls the terminals and data bases. 

• The message £rocessing Procjr.am (MPP) region hosts the application 
programs for message driven processing of the data bases. The MFF 
region is controlled by and relies upon the CTL region. 

• The batch messace irecessing (BMP) region contains an application 
program for batch processing of the data bases managed ty the CTL 
region. 

Once the IMS/VS control region or partition and one or more message 
processing regions or partitions have been initialized by the operating 
system jot management facility, the following system flow occurs. See 
Figure 1-15. 
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Figure 1-15, JMS/VS Data Base/Data Communications System Flow 



The following notes relate to the circled numbers in Figure 1-15. 

1. The data communication facility (event 1) reguests restart 

instructions from the master terminal. After the completion of 
restart, the master terminal enables communication from all user 
terminals (event 2) . 

2- When an input message or message segment is received (event 2), data 
communication calls the common service (event 3) , and the input 
message is logged (event 4) and gueued (event 5) . 

3. When there are input messages gueued and waiting for processing, and 
a message processing region or partition becomes available, control 
is passed to scheduling to determine the application message 
processing program to be scheduled. The application program is 
loaded (if needed) into a region/partition and given control. 



4. 



5. 



6. 



The application program subseguently makes reguests for the input 
message and/or data base reference (event 6) . Control passes to 
DL/I for either message reference (event 7) or data base reference 

(event 8) . The message reference is accomplished through common 
service- 
While the application program is executing, modifications can be 
made to the data base (event 8) and/or output messages may be gueued 

(events 5 and 7) . 

When the application program terminates or reguests another input 
message, all its gueued output messages are transmitted to the 
designated output terminal (s) (events 3 and 2) in our subset- 
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BATCH PFOCESSING OF ONLINE DATA BASES 

Once the IMS/VS control region or partition has been initiated by the 
operating system, a batch mgsjgage processing (BMP) region or partition 
can be initiated. The application program in the BMP region or 
partition is scheduled by operating system job management. Its 
execution, however, is controlled by the IMS/VS control region. This 
BMP region or partition may contain an application program for batch 
processing of online data bases. DL/I is ussd for data base reference 
and update (Figure 1-15). Any data reference is initiated by the batch 
message processing program (event 9) • 

DATA_COMMDNICATION_ADMINISTRATION 

The data base administration function as introduced in the first part of 
this chapter is extended and complemented with a data communication 
administration function in the IMS/VS DB/DC environment. 

DCA CHAEACTEEISTICS 

• DCA provides standards for and controls the administration of the 
online system and its data base use. 

• DCA provides standards and guidelines for message format service 
usage and enforces the administration of device and message formats. 

• DCA is responsible for the transaction and logical terminal security 
control. Passwords should be regularly changed and the security 
maintenance utility should be used in a controlled manner. 

• DCA maintains the logical terminal, physical terminal, and mode or 
physical line assignments. DCA interfaces with network control or 
provides that function itself. 

• DCA is the central contact function for a user liaison group or 
implements that function itself. 

SAMPLE^IMS^VS^DB^DC^PEOJICT^fLAN 

The sample IMS/VS DB project plan as discussed earlier in this chapter 
(see Figure 1-12) can easily be extended to the IMS/VS DB/DC 
environment. Figure 1-16 shows a gross PERT chart for such a project. 
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Figure 1-16. IMS/VS-DE/DC Installation Flan PERT Chart. 

The following activities should be extended or added to the DB-only 
version. 

lnstall_VTMi.N£P_and_IMS^VS_i3002itCOl.: The system programmer installs 
VTAM, NCP~(if remote networkf and'the IMS/VS DB/DC system. 

DC_G r os s_Desian^ J 300 - 4J0]_ : The transactions, programs, device and 
message formats, and their interrelations are defined. 

Detail MFS Design and Coding. (<*2Q-520) : The formats are developed in a 
standard way. They are tested'with their corresponding message 
processing programs. 

£§sign_MTO_Guide_and_MTO_Trai^ The IMS/VS Primer Master 

Terminal Operator's Guide should te adapted to your environment and used 
in the training cf the MTO. 

Desi3n_ETO_Gui4e_.and_0ser_T^ The IMS/VS Primer Bemote 

Terminal Operator's Guide should bs adapted to your environment and used 
in the training of the remote terminal operators. The end user 
departments should be educated in a timely manner in the use of an 
online system. 

IMS/VS PBIMEB FDKCTICN SUBSET CVEBVIEH 

The IMS/VS Primer Function is an implicit, open-ended subset of standard 
IMS/VS functions. The subset selected is aimed at the first time IMS/VS 
user, developing his first and simple IMS/VS application- Following is 
a brief overview of the IMS/VS Primer Function subset. 

This overview is mainly aimed at the existing IMS/vs user. It should be 
used to identify the usability and/or limitations of the Primer Function 
in your environment. 
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Eata Ease Subset 

DL/I Storage Crganizaticn and Access Methods: 

Only HDAM, HIDAM, SHISAM, and GSAM (ESAM) 

VSAM, OSAM, and ESAM (for GSAM) 

No ISAM or OSAM for HIDAM 

Single data set groups 

Single volume OSAM data set 

Nc variable length segments 

No segment compression 

No EL/I exits, except HDAM randomizing modules 

No hierarchic pointers 

Basic rules/recommendations for pointer selections 

SCAN=3 Jdefault) in EBD 

Only HIDAM free space distribution parameter (FRSPC) 

No BLOCK or RECORD parameter in DBD; mandatory SIZE parameter 

No 3850 support 
ogical Relationships : 

Only bi-directicnal virtual pairing 

No uni-directional cr bi-directional physical pairing 

Mandatory RULES=VVV for logical child segment 

Mandatory BUIES=PLV for physical and logical parent segment 

Mandatory physical storage of logical parent concatenated key 

Mandatory sequence field in logical path to the logical child 

Basic rules/recommendations for pointer selection 
Secondary Indexes: 

Root segment is always target segment (no inverted structures) 

No overflew data set (ESDS) ; mandatory /SX field if non-unigue keys 
in index pointer segment 

No shared indexes in a secondary index data base 

I/I Call Functions: 

GU, GN, GHU, GRN, ISFT, BEE1, and DIET calls 

XBST and CHRP calls (only extended checkpoint/restart function) 

No Boolean qualification statements in segment search arguments 
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D, N, F, L and - command codes (path call included) 

No multiple positioning (multiple PCBs will be used) 

Data Base Design: 

Simple data rase design technology based on the transaction/data 
element matrix 

Basic rules/guidelines for logical and physical design, including 
organization, access method, and pointer attribute selection 

Data Ease Reorganization: 

All logical related data bases are reorganized at the same time 
(data base scan utility not used) 

No utility ccntrol facility (OCF) 

Simple guidelines for icnitcring reorganization requirements 

No partial reorganization 

Data Base Recovery: 

Recovery with and without DL/I log tape 

Mandatory log data set change accumulation 

Mandatory write ahead leg tape 

Log tape recovery 

No utility ccntrol facility (UCF) 

Simple procedural guidance for data base error detection, 
classif icaticn, and recovery 

Easic guidelines for image copy and log tape administration, and 
data set retention periods 

No online image copy 

Installation and Operation: 

Only 0S/VS1 and OS/VS2 (MVS) support 

VSAM is mandatory 

The IMS/VS BE installation process is described separately from the 
EE/EC installation process 

No ACBLIB for data base only system 

Simple interpretation guidelines for EB Monitor output and data base 
buffer pool statistics 

No support for power warning feature 

Sample application programs written in both ANS COBOL (compiler 
used: OS/VS CCBOI, 5740-CE1) and EL/I (optimizer compiler used: 
573H-PL3) 
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Eata Communication Subset 
Device Support: 

• IBM 3270 Information Display System, the following control units and 
attached terminals, via ETAM or VTAM, locally or remotely attached: 

3271 Model 1, 2, 11 cr 12 

3272 Model 1 cr 2 

327H Model 1B or 1C (BSC line protocol only) 

3275 Model 1 or 2 

3276 Model 1, 2, 3, or 4 (BSC line protocol only) 
DL/I Message Call Functions: 

• GU, GN, ISB1, and CHKG calls 

« XEST/CHKP call ccmbinaticn fcr BMPs 
Message Format Service: 

• Only message formatting option 2 

• Dynamic cursor positioning via attribute byte only 

• Single segment input 

• No multiple page input 

• One output segment equals one logical page, equals one physical page 

• Logical paging, no physical paging 

• No device type nixing in MFS 

• No program function keys (PFKs) 

• No message field and segment edit routines 

• Nc prompt facility 

• No cperatcr control tables 

• No selector pen 

• No operator identification card reader 
Kessage Processing: 

• Only single segment input messages 

• Multi segment output message 

• Maximum length cutput segment of 1388 

• Only response mode transactions 

• Non recoverable inquiry only transactions 

• Eecoverable update transactions 

1.38 IMS/VS Primer 



Conversational transactions, vith fixed size nain storage scratch 
pad area (SPA) of 1300 bytes 

Data Communications Design: 

Concepts of online transaction design, based on application, 
terminal user, and systetr characteristics 

Basic MPP structure for simple inquiry, update and conversational 
programs 

Easic guidelines fcr screen design 

On-line data base design considerations 

nstallation and Operation: 

Long message gueue record length of 1500 bytes 

Short message gueue record length of 250 bytes 

VTAM or ETAM; no mixture 

Forced terminal and password security 

No exit routines in IHS/VS except HDAM randomizing modules 

Cne MPP and one EKE region 

No message gueue access via BMP 

Mandatory IMS/VS shutdown for data base recovery or reorganization 

Single mcde transaction scheduling 

Single transaction scheduling class and priority 

No program-to-program switching 

Sample set of VTAK level 2 definition statements 

Sample set of NCP/VS definition statements to be used with IMS/VS 
and VTAM Level 2 sample definitions 

Single log tape only 

No online DOMFQ 

No disk logging and enhanced restart 

No automated operator interface support 

No resource access control facility (RACF) support 

Mandatory hardcopy of all eligible master terminal commands and 
responses 

Only /ASSIGN, /EROADCAST, /CHECKPOINT, /CLSDSI (VTAM only), /DEEUMF, 
/DISPLAY, /EFESTART, /EXIT, /FCFMAT, /HCLD, /IELE (ETAM only), 
/NRESTART, /OPNDST (VTAM only), /PSTOP, /P0RGE, /BCLSDST (VTAM 
only), /RELEASE, /BSTART, /STABT, /STOP, and /TRACE commands for the 
Master Terminal Operator 

Only /EXIT, /FORMAT, /HOLD, /RCLSDST, and /RELEASE commands for the 
Remote Terminal Operator 
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As in almost any system implementation, the design is the most 
challenging task to be performed. The best optimization or tuning 
effort which you can perform is a sound initial design. On th€ ether 
hand, a designer is often bound to a time limit and does not know all 
future reguirements. To cope with these problems, a designer needs a 
good plan and proper technigues. 

The mest crucial topic in the design of applications with data base 
management systems is the data base desioru In this chapter we will 
introduce data base design with DL/I- We will also provide guidance in 
selecting these EL/I functions which will result in an open-ended 
design- Oui major objective is a good overall design resulting in good 
overall performance rather than a design which maximizes the performance 
of a single application program. 

Should you have a specific performance objective for a particular 
application, then ycu are advised tc study Chapter 9, "Optimization," in 
detail after reading this chapter, and before starting your actual data 
base design. 

ABOUT_THIS_CHAPTJR 

This chapter consists cf three parts. 

1. Introduces the sample application in detail. It sets the 

reguirements and the environment for the actual data base desigr 
process. It is meant tc give the background for the examples used 
in the two following parts. 

2- Introduces the functions of DL/I, available to the data base 

designer. It alsc certains the specification cf the DL/I data base 
definition language- This part will be the major reference area 
after the initial study of this chapter. 

3. Introduces the concepts, techniques, and guidelines for the 

designing of data bases with DL/I. It is aimed at those individuals 
who are designing their first data bases with DL/I. As such, it is 
more oriented towards learning than referencing. 

Each cf the above three parts is constructed along the three phases of 
data base implementation: 

• Phase 1: Basic data bases 

• Phase 2: lata bases with logical relationships 

« Phase 3: Data bases with secondary indexes 

With this gradual approach you should be able to design simple data 
structures with a minimal ancunt cf effort and still be able, when the 
need arises, tc exploit the full DL/I function. Once again, you should 
realize that data base design is net just a matter of creative 
imagination- Most of it is systematic labor* The intent of this 
chapter is to help ycu with this, by providing techniques for an 
efficient accomplishment of this challenging task- 
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PHASE 1 SAMPLE REQUIREMENTS 



P2J?2S_j;ata_E as e_Con tents 



Following is a list cf all the data elements tc be stored in the FAETS 
data base together with their system names. The system name follow the 
naming convention described in Chapter 1. 



PIIIIL Cat a_ El e m e nts : 

Name 

FE1FGDSC 

FE1FGSNH 

EE1PGPNR 

FE1FG0NT 

FE1PGPRI 

FE1PGDIM 

EE1PSLCC 

FE1PSCNT 

FE1PSDAT 

FE1PSISS 

FE1PSREC 

FE1PPOSU 
FE1PEQCD 
FE1PPQRE 
FE1PP0DT 
FE1PPDDT 
FE1PPONR 
FE1FGNEW 
FE1PGOLE 
FE1PGEQV 



Sfscji^tion 

Part name, full description 

Patt name, short description 

Pait number code 

Unit of measure for quantities 

Part case price 

Unit dimensions 

Stcck physical location code 

Stcck physical count quantity (tally) 

Date of last physical stock count 

Total issued frcm stock in current 

period 

Total receipts to stcck in current 

period 

Suppliers name 

Quantity ordered 

Quantity received 

Purchase order date (MMEDYY) 

Delivery date (MMEDYY) 

Purchase crder number 

New Isuperseding) part number 

Old (superseded) part number 

Equivalent part number 



length 

" 50~~ 

13 

8 

e 

8 
8 
12 
6 
6 
6 



20 
6 
6 
6 
6 
8 
8 
8 
8 



l5M£tcrv_Re£ort_Processing 

Every week a report is made of all the parts in stock with a listing cf: 

Part number 

Part name, short 

Part name, long (optional) 

Quantity in stock 

Quantity issued frcff stcck in current period 

Quantity received in current period 

Quantity en crder 

We will refer to this application function as transaction TE1INVPF. On 
demand (averaging twice a day) , the same information is needed for 
specific parts, ncrnally 1 tc 10. This transaction, TE1INVQU should be 
designed with the idea that it will be done online at a later stage. 
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PurcJjase_Order_Processin3 

Daily, an average of 1C0 orders are processed, each containing an 
average cf 2 parts and a maximum of 6. The purchase order forms, 
delivered by -the purchase department, are keypunched and sorted in 
purchase order/part number sequence- This application is also planned 
to go online in the near future, with video terminals installed at the 
purchase crdez department- 

Note: An order signal list could be produced in the same prograi which 
generates the weekly parts inventory report but this will not be 
addressed in our sample. 

The functions performed by this application are: 

• Entry of new orders, transaction TE1PCNEW. 

• Change of existing orders, transaction TE1P0CNG- 

• Deletion of orders after delivery, transaction TE1P0DEL. 

PHASE 2 SAMPLE SECUIRESENTS 

Samj:le_Data_Eases_f or_|hase_2 

in the phase 2 environment we will add the Customer Order Processing 
Application. This application requires information from the: 

• Existing Parts data base 

• Existing Central Customer file 

• New Customer Orders data base 

The data elements required from each of these are described below. 

Pa r ts_D a ta_ Elements: Primarily the same data elements as in phase 1 are 
required, although some are not used in this application. 

Central^C ust cmer_Da ta ^Elements : 

Name description Length 

FE2PCNUM Customer Number 6 

EE2PCNAH Customer Name 20 

FE2PCADB Customer Address 20 

TE2PCCTY Customer City 20 

IE2PCPCE Postal Code 6 
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Cfistoffl€£_0rder_Cata_El€ji6i}t£: 



Name 


Descrij: tion 


EE20GREF 


Order Number 


FE2CGSTA 


Order Status Code 


IE20GCNR 


Custcmer Number 


FE20GCDT 


Order Entered Date 


EE20GEDT 


Order Due Date for Delivery 


FE2CGDWK 


Order Eue Week for Delivery 


IE20GSPC 


Special Delivery Instructions 


FE20G0RI 


Order Crigin Code 


FE20CPNP 


Part Number This Orderline 


FE2CD0.T? 


Part Quantity Ordered 


EE20DPRI 


Part Base Selling Price 


FE20DTAI 


Part Sales Tax Category 


FE20SNR 


Shipment Number 


FE2CSDAT 


Shipment Date MMDDYY 


FE2CSMET 


Shipment Ketbod 


FE20EE0R 


Backcrder Flag 


Samjgle Amplication 


for Phase 2 



length 

6 
2 
6 
6 

6 
2 

20 

2 

8 

6 

8 

1 

8 

6 
20 

1 



The sample application fcr Phase 2 is Customer Order Processing. This 
consists cf three basic transactions: 

TE2CGNEW — adds a new custcmer crder to the Customer Orders data 
base 

TE2COCNG -- changes data in an existing customer order 

IE2CCDEI -- deletes a customer order from the data base 

The customer crder characteristics are: 

An average of 5C0 orders per day, maximum of 1000 

Each crder contains a maximum of 8 crder lines* one order line for 
each part type ordered, an average of 3 order lines per crder. 

The average delivery time cf an order is two weeks. 

After delivery, the crder is deleted from the data base. 

Access to the order information is reguired via both the order 
number and the part number (the latter, for changing the crder 
whenever changes tc the status of a part occur) . 

Additionally, another application reguires access to the customer orders 
fcr each part. So we must link the part and customer order information. 
The customer name and address are alsc needed during customer order 
processing. This information is maintained in the Accounts Receivable 
application which will net be cenverted at this time. This information 
is stored in a VSAM KSES. The key of this KSDS is the customer number, 
which will be stored in the Customer Order data base for reference. 
This KSDS will be defined and accessed as a root only DL/I data base. 

The advantages to this approach are: 

• The current KSES is still available fcr the non-EL/I Accounts 
Beceivable application. 

• The same KSDS can be processed as a DI/I data base, thus allowing 
the new customer application full EL/I function™ 
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• This root only data base can easily be extended with additional 
segments when the accounts Beceivafcle application is converted to 
DL/I. This conversion can be done with minimal impact on the 
Customer Order application. 

PHASE 3 SAMPLE FEC.UIFEKENTS 

For the phase 3 sample application, we incorporated one additional 
requirement for the purchase order application. This requirement 
provides fas.t purchase order information for one or more purchase 
orders, based on the purchase order number. To implement this new 
transaction, 1E3ECINC# we will utilize the secondary index function of 
EL/I. 

IHJ_£L^I_DATA_EAS!_IAC3LI2J 

This part of Chapter 2 provides an introduction to the DL/I functions 
and their use. It is the nain source of reference for the data base 
designer and/or data base administrator. This part is subdivided into: 

• A discussion cf the DI/I data base organizations 

• A presentation of the DL/I data base definition language 

The first part provides the insight into DL/I necessary for the data 
base design- The second part provides details for the implementation of 
the data base(s). Each part has three sections. These sections cover 
the following main data base facilities: 

• Physical data bases and storage organizations 

• Logical relationships 

• Secondary indexes 

FHYSICAL DATA BASE AND STORAGE ORGANIZATIONS 

To support a wide variety of data base requirements, DL/I provides 
several data base storage organizations- However, your application 
programs will fce typically iEdependent of the particular organization 
chosen for a given data base. 

In our subset, we will limit ourselves to the following data base 
storage organizations and their associated data base types. 

2i3§£iZSli££ £§£a_I.§§§_Ty.Ee 

Eierarchical Eirect Access Method HDAM 

Hierarchical Index Direct Access Method HIEAF 

Simple Hierarchical Index Sequential Access Method SHISAM 

Generalized Seguential Access Method GSAM 

The data base type, its organization, and structure are defined in the 
data base description (DEC). To use a data base in an application 
program7*you must provide a irc^ram specification block (PSB) . The PSE 
specifies the data base (s) tc be used and the kind of usage required. 
DBDs and PSEs are created during data base description generation 
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(DBDGEN) and program sgecif ication block generation (PSBGEN) , 
respectively. Ihis is discussed in detail later in this chapter. 

Before discussing each of the above organizations in detail, ve will 
first elaborate some acre en some basic CL/I concepts vhich were 
introduced in Chapter 1. 

The^DL^/I^Cata^Ease^Reccjd 

As introduced in Chapter 1, a DL/I data base record as shown in Figure 
2-1 consists of one root segment and a number of dependent segments. 
Each dependent segment car. have a variable number of occurrences below 
its parent occurrence. 



PARTn 



STOCKn3 



STOCKn2 



STOCKnl 



| ORDERn2 



ORDERnl 



DETAILn11 



Figure 2-1. A EL/I Data Base Record 



In its most elementary fcrm, this record could be stored in one or more 
physical records. In principal, the segments would be stored in their 
hierarchical sequence, as shewn in Figure 2-2. 
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RECORD 
M-1 



RECORD 

M 



RECORD 

M+1 



DL/I DATA BASE 



PARTn-1 



PARTn 



STOCKnl 



STOCKn2 



STOCKn3 



ORDERnl 



DETAILn11 



ORDERn2 



PARTn+1 



Figure 2-2. A EL/I Data Base Fecccd in Physical Storage 

It should be noted that the abcve figure is a simplification. In 
reality DL/I uses more elaborate storage organizations to allow for 
efficient replacement, inserticn, and deletion of segment occurrences. 
Generally available functions include, for example: 

• Space re-use of deleted segments 

• Chaining of segments tc be added later in the right hierarchical 
segue nee 

• Direct or key-sequenced access for the root segment based on the 
root segment seguence field (=key field). 

This will be discussed in more detail for each of the data base 
organization methods. 

Segment .Format 

A segment in a DL/I data base record consists of a prefix and a data 
portion. The prefix contains xhe system data used by DL/I and is not 
presented to application programs. The data portion contains the user 
data as seen by the application prcgram. The prefix of a segment 
contains a segment code, a delete byte, and optional pointers. 



-PREFIX 



DATA 



SEGMENT 
CODE 



DELETE 
BYTE 



POINTER AREA 



TC 



Figure 2-3. Segment Format 



FIXED LENGTH 
USER DATA 
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The one-byte segment code is used to identify the segment- It is the 
first fcyte of the prefix. The second byte is the delete Jbjte- It is 
used to maintain the status cf a segment within the data base. 

Note: SHISAM and GSAW data bases can contain only one segment type. 
These data base organizations do not contain segment prefixes. 

Pointers are used in HEAK and HIDAM data bases for linking the segments 
within one data base record in their hierarchical order. Pointers are 
also used to link segments involved in logical relationships, and to 
implement index pointing. The segment types in each data base are coded 
in hierarchical seguence from 1, the root segment, up to 255, as shewn 
in Figure 2-4. 





1 






























2 




5 




















3 


4 





Figure 2-4- Segment Iypes Numbered in Hierarchical Sequence 

Note that each occurrence in a data base of a given segment type 
contains the same segment code. Each segment occurrence is normally 
identified by its concatenated key. 

The_Concatenated_K6y. 

The concatenated key, of a segment consists of all keys from the root 
down the hierarchical path to and including the key of the segment 
itself", as shown in Figure 2-5. 
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CONCATENATED KEYS 



J 



PART 
~}> 01001020 




01001020 



STOCK 
KBL070100010 



SEQUENCE FIELD KEYS 




> 




01001020KBL070100010 



> 





ORDER 
75456-01 



0100102075456-01 



DETAIL 
03 



0100102075456-0103 

■ • • • 



Figure 2-5. Concatenated Keys 



A unique concatenated key is net required for every segtuent. However, a 
unique key is required for the root segment, except for HDAM. 

Calls_and_Data_Ease_ Positioning 

For a better understanding of each particular data base organizaticn, we 
include now a basic description cf the DL/I calls used to process 
segments in a data base. 



The segments in 
an application 
replace a segme 
list which incl 
Included in the 
SSAs Jsegment s 
be performed, a 
path dewn to, a 
unqualified whe 
cne cr more SSA 
used in process 
For more detail 
Processing. " 



a DI/I data 
program, cal 
nt or a path 
udes all data 

list are a f 
earcb argucec 
nd the SSAs d 
nd including, 
n no SSA is i 
s are include 
ing a data ba 
ed informatic 



base are processed through calls issued by 
Is are issued to y*et, insert, delete, or 
of segments. A call references a parameter 

reguired by Dl/I to complete the call, 
unction code and, optionally, one or more 
ts). The function code states the call to 
efine the segments alonq the hierarchial 

the segment to be processed. A call is 
ncluded with the call, and is Sfia.iifi.ejl when 
d. A brief description of the primary calls 
se and a brief description cf SSAs follows. 
n, refer to Chapter 4, "Data Base 



The basic direction of mcvesert in a DL/I data base is "top to bcttcm, 
left to right." Position in a data base is the segment or segments from 
which the search for another segment starts. Normally DL/I retains 
position at each level of the hierarchical path down to the last 
retrieved segment. 
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^§i-.5£i9a§ : The GD l9 €t unique) call is used to retrieve a specific 
segment or path of segments frci a data base. At the same tine it 
establishes a position in a data base frco which additional segments can 
be processed in a forward direction. 

Get_Next: The GK Jget next) call is used to retrieve the next desired 
segment or path of segments frco a data base. The get next call 
normally moves forward in the hierarchy of a data base from the current 
pcsition. It can be modified to start at an earlier position than 
current position in the data base through a command code, but its normal 
function is to move forward from a given segment to the next desired 
segment in a -iata base. 

£2i£_f!£.£fi-2iL<2§£_£ili§ : A GHa (9 et hoid unique) , or GHN (get hold 
next), indicates the intent of the user to issue a subsequent delete or 
replace call. A get hold call must be issued to retrieve the segment 
before issuing a delete cr replace call. 

Insert: The ISRT (insert) call is used to insert a segment or a path of 
segments into a data base. It is used to initially load segments in 
data bases, and to add segments in existing data bases. 

To control where occurrences of a segment type are inserted into a data 
base, the user normally defines a unique seguence field in each segment. 
When a unigue sequence field is defined in a root segment type, the 
sequence field cf nach occurrence of the root segment type must contain 
a unigue value. Mhen defined for a dependent segment type, the sequence 
field of each occurrence under a given physical parent must contain a 
unique value- If no sequence field is defined, a new occurrence is 
inserted after the last existing one. 

Delete: The ELEI (delete) call is used to delete a segment from a data 
base. When a segment is deleted from a DL/I data base, its dependents, 
if any, are also deleted- 

Eeglace: The EEFL (replace) call is used to replace the data in the 
data portion of a segment cr path of segments in a data base. Sequence 
fields cannot be changed with a replace call. 

1§.L (§§afi£Bi i§§£2^ Argument): An SSA specifies the conditions which a 
segment must meet to satisfy the call. An SSA can contain three parts. 
As a minimum,, it contains the name of the segment type. Optionally, an 
SSA can also contain command codes and/or qualification statements. 
Commands codes, when used, specify a functional variation of a call, 
such as: retrieve last occurrence of the segment under its parent- 
Qualification statements identify, through field values, the segment 
occurrence of the specified segment type. A qualification statement 
contains a field name, relational operator, and comparative value. When 
occurrences of the segment type are searched by DL/I, the specified 
field is compared tc the comparative value as the relational operator 
specifies. If only the name of the segment type is specified, the first 
encountered occurrence cf that type will satisfy the call. 

OSZVS_Access_Methods_Us€d_by_DL^I 

For each data base organization, DL/I uses one or more OS/VS access 
methods for the actual storage and retrieval of the data base records. 
Ccmmcnly used access methods are: 

• The key sequenced data set (KSDS) and entry sequenced data set 
(ZSES) of the virtual storage access method (VSAH) of CS/VS. 
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• Overflow sequential access method (OSAM). This is a special 
physical access method supplied with DL/I. As far as CS/VS is 
concerned, an CSAM data set is described as a physical sequential 
data set (DSORG=PS). 

HDAM ANE HIDAM STORAGE ORGANIZATIONS 

Both of these data base organizations are implemented with the 
hierarchical direct methcd cf segment storage- In the hierarchical 
direct method, the segient occurrences in a hierarchy are connected in 
storage via fcur byte direct address pointers in the segment prefixes. 
A description of the types cf pcinters used in HDAM and HIDAM data bases 
can be found at the end of this section. 

Twc of the primary advantages of EEAM and H3EAM data bases are space 
reuse and the ability tc directly access segments within the data base. 

The segment storage organization used for HDAM and HIDAB data bases is 
essentially the same- The primary difference, at the access method 
level, tetween BEAM and HIDAM data bases is that access to occurrences 
of the rcot segment type is through a user randomizing module fcr an 
HDAM data base, and through an index for a HIDAM data base. To access a 
given rcct in an HDAM data base, the randomizing module examines the key 
of the root, and through hashing cr some other arithmetic technique, 
computes the address of the rcct and passes it to DL/I V To access the 
same rcct in a HIEAM data base, an index must be searched by DL/I tc 
find the address of the rcct- When found, the root is accessed- By 
using a randomizing module to locate roots, the I/O operations required 
to search the index are eliminated- On the other hand, sequential 
processinq of data bas€ records is not necessarily in root key sequence, 
with HDAM- 

HDAM: Refer to Figure 2-6 fcr the following discussion. An HDAM data 
base consists basically cf cne ESES or OSAM data set. To access the 
data in an HEAM data base, DL/I uses a randomizing module. The 
randoitizing module is used by EL/I to compute the address for the roct 
segment in the data base. This address consists of the control interval 
(CI) , if VSA£, or block, if CSAF, number, and an anchor point number. 
Anchor point (s) are located at the beginning of the Cl/blocks. They are 
used for the chaining cf rcct segments which randomize to that Cl/block. 
A general randomizing module is supplied with the system. See the 
section "HDAM Bandomizing Kodules" in Chapter 7, which also contains 
guidelines to help ycu write ycur cwn randomizing module if required. 

The ESDS or OSAM data set is divided intc two areas: 

• The root addressable area. This is the first n control 
intervals/blccks in the data set- You define n in your DDD. 

• The overflew area is the remaining pcrticn of the data set. 

The root addressable area is used as the primary storage area for 
segments in each data base record- The overflow area is used fcr 
overflow storage. Since data base records vary in length, a parameter 
|in the DBD) is used to control the amount of space used for each data 
base record in the roct addressable area. This parameter, "bytes" in 
the EMNAME= keyword, limits the number of segments of a data base record 
that can be consecutively inserted into the root addressable area- When 
consecutively inserting a rcct and its dependents, each segment is 
stored in the roct addressable area until the next segment to be stored 
will cause the total space used to exceed the specified number of bytes. 
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The total space used for a segment is the combined lengths cf th€ prefix 
and data portions of th€ segment. When exceeded, that segment and all 
remaining segments in the data base record are stored in the overflew 
area. It should be noted that the "bytes" value only controls segments 
consecutively inserted in one data base record. Consecutive inserts are 
inserts to one data base record without an intervening call to process a 
segment in a different data base record- 
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Figure 2-6. REAM Data 3ase in Physical Storage 



iiJEAM: A HIDAM data base in auxiliary storage is actually comprised of 
twe data bases that are normally referred to collectively as a HIDAM 
data base. When defining each through the DBCGEN utility, one is 
defined as the HIDAM prinary index data base and the other is defined as 
the main HIDAM data base. In the following discussion the term "HIDAM 
data base" refers tc the fain HIDAM data base defined through DECGEN. 

The HIDAM primary index data base is used to locate the data base 
records stored in a HIEflM data base. When a HIDAM data base is defined 
through DEDGEN, a unique sequence field must be defined for the root 
segment type. The value of this sequence field is used by DL/I to 
create an index segment fcr each root segment. This index segment in 
the HIDAM primary index data base contains, in its prefix, a pointer to 
the root segment in the main HIDAM data base. 
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The HIEAK primary index data base consists cf a KSDS; its only data (and 
key) is the sequence field of the root segment. In our subset, the main 
HIDAM data base consists of one ISES. The segment storage organization 
in this EST.S is comparable tc the cne in the HDAM ESDS. Figure 2-7 
shews the layout of the HIDflK data base. 
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figure 2-7, HIIAK Data Base in Physical Storage 



Inserts and Deletes in HEAE and HIEAM 



The techniques used to inser 
HDAM and HIDAM data bases, 
space available chains, and 
fields are used by DL/I tc f 
record free space when a seg 
segment occupies is inmediat 
Ycu only need to be aware of 
Cl/blocksize calculations be 
selected Cl/blocksize- We w 
such calculations later in t 



t or delete segments are the same fcr both 
The techniques involve use of bit maps, 
available length fields- These system 
ind space when inserting a segment, or to 
ment is deleted- Normally, the space a 
ely freed after the deletion of the segment„ 
these system-maintained fields when doing 
cause they are allocated within your 
ill cover this when providing guidelines for 
bis chapter- 



Alsc, with HIEAK, you can specify free space at data base load time 
(initial lead or reload during reorganization) . This is specified in 
the pEE for the rSDS. For the primary index KSDS, free space can be 
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assigned Kith the VSAM access method services DEFINE command. In 
theory, you can alsc specify free space in the DED for an BEAM data 
base. This is, however, not recommended because it night conflict with 
the randomizing mcdule algorithm, 

l2i££€rs_in_HrAH_and_HipAf1 

To link each segment in an HDAM or HIDAM data base to its related 
segment, direct address pointers are used- The pointers are four bytes 
long, and are placed by DL/I in the prefix of each segment stored in the 
data base- A direct address pointer consists of the relative byte 
address of a segment frcir the beginning cf a data set- 
Note: The following discussion of pointers is included for those of you 
whc are interested in the internal DL/I storage organization. A 
complete comprehension is not reguired for basic data base design, 
because we will give detail guidelines fcr the necessary pointer 
selection in the implementation part. 

The most common method is a combination of £h_ysical child/£hysical twin 
pointing. Figure 2-8 should be referred to when reading the following" 
description cf pointers. 

JEkl§iS§i-£lii.I4^IllY§i?§I_l!*ill_l2illi®£§ : Every parent segment in the data 
base has a pointer to the first occurrence of each of its child segment 
types. This is the physical child (first) pointer. Optionally, per 
child segment type, there is also a pointer to the last occurrence of 
that chile segment type, the £hjjsical child, last pointer. This physical 
child last pointer will iirprcve segment insert performance of that child 
if that segment has no sequence field defined. It also improves the 
performance of a get call which, via a command code, explicitly reguests 
the last segment occurrence. 

Usually, every segment in a HIDAM or HDAM data base has a pointer in its 
prefix which points to the next {based on sequence field) occurrence of 
this segment under the sase parent. (If it is the last occurrence under 
the parent, this pointer is zero.) This pointer is named the .physical 
iSiD (tS£*^£§) EfiiSi§£- tt i* i s the root segment, the physical twin 
pointer points to the next root if HIDAM- In HTAM, the physical twin 
pointer is used to chain the rcot segment (s) of the anchor point. If 
there is never more than one occurrence of a segment for a given parent, 
then you should omit this pointer. 

Optionally, you can alsc select a pointer in each segment prefix which 
points tc the previous segment occurrence under the same parent. This 
is the fihy^sical twin backward pointer- This pointer will improve delete 
performance if the segment tc be deleted is a logical child cr is 
located via the physical child last pointer (that is, command code 
last) . 

In addition, when physical twin forward and backward pointers are 
specified for the rcct segment type of a HIDAM data base, they enable 
seguential processing across data base records without intervening 
references to the HIDAM index. When only physical twin forward pointers 
are specified for the root segment type of a HIDAM data base, sequential 
processing across data fcase records reguires intervening references to 
the HIDAM index. In our subset, we will always select physical twin 
forward and backward pointers for the rcct of a HIDAM data base. 
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Legend : 

PTF: Physical twin forward pointer 

PTB: Physical twin backward pointer 

PCF: Physical child first pointer 

PCL: Physical child last pointer 

Note that PTB and PCL are optional. 
Figure 2-8. Direct Address Pointers in HDAH and HIDAM 

SHISAM S1CBAGE CBGAKIZSTICK 

The data structure of a SHISAM data base consists cf only one segment 
type, the root segment, with a unique sequence field. Because of this, 
there is no segment prefix needed- The physical storage organization is 
a single VSAM KSDS JKey Seguenced Cata Set). This makes it possible tc 
process a non EL/I KSDS as a DL/I data base with full Dl/I function. 
The main use of the SHISAM organization is as a migration tool tc DL/I 
for existing KSD3 or ISAM files. It is net recommended for new data 
bases. (See also the phase 2 sample environment earlier in this 
chapter.) 

Note: The logical record length cf the KSDS must be an even numfcer for 
SHISAM. 
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FUNCTIONS AND USE OF GSAM 

An OS/VS sequential file can be defined to EL/I as a GSAM data base. 
However, the normal concepts of hierarchical structures do net apply to 

GSAM. 

When using GSAH for sequential input and output files, Dl/I will ccntrol 
the physical access and pesitien of those files. This is necessary for 
the repositioning of such files in case cf program restart. When using 
GSAM, Dl/I will, at restart time, reposition the GSAM files in 
synchronization with the data base contents and your application 
program's working, storage. To control this, the application program 
should use the restart (XHST) and checkpeint (CHKF) calls. These calls 
will be discussed in Chapter 4, "Data Ease Processing." 

When_tc_Ose_GSAM 

Whenever you want your program to be restartable, you should use GSAM 
for its sequential input and output files. There are two reasons why 
ycu should want to do this- The first is to save time if a program 
rerun is required in case cf program or system failure. This is 
normally enly done for long-running update programs (one or mere hours). 
The other reason stems frcm a planned online usage of the data bases. 

Tc be able to run a batch program in parallel with the online system, 
using the same data bases, that program must be executed as a batch 
message processing (BMP) program. A BMP runs as a batch job, but uses 
the cnline ccntrol regicn of IMS/VS fcr the access of DI/I data bases. 
In that way, IMS/VS will provide complete data integrity acrcss the 
batch and cnline use cf the data. To do so, however, the IKS/VS data 
base/data communication system will isolate the data base updates of a 
particular program until program termination. By using the checkpoint 
call, the batch program can free those updated data base segments for 
immediate access bj other batch and/or online programs. 

Suj=£orted_Data_Sets 

GSAM supports data sets organized according to the following OS/VS 
access methods: 

« Sequential Access Methos (SAM) 

• Virtual Storage Access Kethod (VSAM) 

GSAM supports the Easic Sequential Recess Method (BSAM) , on DASD, unit 
record, and tape devices and E£DS en DASD devices. In our subset, we 
will enly consider ESAK fixed and variable length record formats. 

The terms segment, segment type, hierarchical, parent, child, etc., are 
not applicable tc GSAM data sets, ncr do the concepts of either key or 
field apply. 

When program restart is required, ycu shculd not use temporary files, 
that is, for SKSIN/SYSOUT spooling. They may be deleted by CS/VS after 
program or system failure. 

A GSAM data base may also be a data set previously created ty use cf 
OS/VS ESAM, or QSAM. Conversely, a GSAM data base may be accessed later 
by ether programs using these CS/VS access methods. 
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PLZ2-iiQGICAL_EILATI0N SKIPS 



WHY LOGICAL RELATIONSHIPS 

He have so far addressed only single hierarchical data structures. 
Quite often, especially with different applications, several DL/I data 
bases are needed. In addition, there is often a requirement to access 
the same data in different hierarchical structures and different data 
bases- Ihie can create'prcblems of: 

• Consistency -- if data is stcred more than once, how to update all 
occurrences at the same time. 

• Data Pedundancy -- if large data elements are stored many times, 
this may consume excessive external storage. 

• Access of Data -- if data is stored more than once, which access 
path should be used to access the appropriate copy of the data. 

The above problems car. be sclved by storing the data only once and 
providing a linkage mechanism between hierarchical structures. With 
this linkage a new access path is provided to data in data base A, based 
on data in data base B, and, if desired, vice versa. 
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EUILDING LOGICAI EILATICKSHIf S 

S egm ent_T y.£ e s_ In v c 1 v e d_ i n_ L cg^ 

The following segment types are needed to establish a logical 
relaticnship. All three must be present for any logical relationship. 
You should refer to Figure 2-9 when reading the following discussion. 
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Figure 2-9- Segment Types Involved in Logical Relationships 
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JkSSical CJijULd_ Segment: This segment has two parents. 1 logical Earent 
and a~£h.ysical parent. The logical child segment and its dependents , if 
any, are accessable via both parents. The access path via its physical 
parent is called physical access £ath. The access path via its logical 
parent is called the lexical access jgath. Ey definition, a logical 
child segment contains the concatenated key of the logical parent 
fcllcwed ty user data, if any. The remainder of the user data in the 
logical child is called intersection data. It is present at the 
intersection of the twe parents. The lexical parent concatenated key 
(LPCK) is always presented together with the intersection data, whenever 
the legical child is accessed via its physical path (see Figure 2-10). 

r - ----- - -----------------«------------------------•--.----., 

III I 

| PREFIX | LPCK | INTERSECTION DATA | 

I I I I 

I , I 

|< TC/FROM USER'S I/C AREA >| 

Figure 2-10. logical Child Segment Format 

Whenever you insert a logical child segment in its physical data base, 
you must present the IECK. It identifies the logical parent. 

l22i£32.l2Eint_Segient: This segment may reside in the same or a 
different"data~Ease as the legical child. 

£i!Isical_Parent_S€gment: This is the normal parent segment of the 
lcgical~child in its physical data base as defined earlier. 

The most common method for implementing logical relationsips between 
HEAM and KIDAM data bases is based on direct address pointers, which are 
all 4-byte relative byte address pointers similar to other pcinters in 
HDAM and HIDAM. 

The_VirJ:ualJLogical_Child_S^ To be able to define the view 

of the legical parent on its logical children and their occurrence 
sequencing, DI/I introduces a special segment type. It is Famed the 
SiE^iiSi logical child and is defined as a dependent of the logical 
parent segment. It does not exist in physical storage itself. Its only 
role is tc provide a mechanism to define the legical parent's view cf 
the data in the logical child. It controls the access from the logical 
parent to the logical child. It is used to define the sequencing of the 
logical child segment when that logical child segment is accessed via 
its legical parent. The virtual logical child is said tc be paired with 
the real logical child. See Figure 2-11. 
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PHYSICAL DATA BASES 



LOGICAL DATA BASES 



ORDER 



PART 



DETAIL 



s* 




ORDER 



■and/or- 



PART 



DETAIL 



PART 



DETAIL 



ORDER 



REAL LOGICAL CHILD VIRTUAL LOGICAL CHILD 
(Represents DETAIL when 
accessed from PART) 
Key: 
PP— Physical parent pointer 
LP— Logical parent pointer 
LCF— Logical child first pointer 



CONCATENATED SEGMENTS 



Figure 2-11. Virtual Paired Bidirectional logical Relationship 

When accessed, the virtual logical child contains the concatenated key 
cf the physical parent of the real logical child, plus the intersection 
data of the real, logical child. So the virtual logical child DETAII 1 
in Figure 2-11 contains the key of the OEDEB segment plus the user data 
of the real DETAII segnect. 

3h§ !2§§£iS§£i2S !§£§H£ : With bidirectional pairing, DL/I refers to the 
parent which is ether than the cne used to access the logical child as 
the destination parent. As a consequence, the logical child always 
starts Kith the destination p.arent concatenated key (DPCK)-. 

Logical_and_Pjiysical_Eata_Bas€s 

The jghysicajL data bases used tc implement a logical relationship oust be 
HDAM or HIDAM data bases. Figure 2-12 shows the physical data bases of 
our Phase 2 sample environment. The order line segment in the Customer 
Orders data base is the logical child of the part segment in the Parts 
data base. Notice that the virtual logical child is not shown, although 
it will appear in the DBD as discussed later. 
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Figure 2-12. The Phase 2 Physical Data Eases 
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A discussion en how this structure is derived can be found in the last 
part of this chapter, a logical_data_base is a redefinition cf one or 
more physical data fcas«s which contain logical relationships. It yields 
a new hierarchical structure which is cenposed of structures from both 
related structures- The new structure can be processed by application 
programs as if it were physically present. The logical data base can 
only be defined if the proper logical relationships are defined in the 
physical data cases. 

The_Concatenated_ Segment: All segments in the logical data base stem 
frcm one segment in one of the physical data bases, except when the 
logical child is accessed. Whenever the logical child is accessed in a 
logical data case, it is optionally, concatenated with the destination 
parent segment. See Figure 2-13. The destination parent is the parent 
of the LCHILD ether than the one frcm which you came. 

r --- -.------------------------------------------------.------.«.--- -^ 

| LOGICAL CHILD | | 

| | EESTINATION PARENT | 

1 EPCK 1 IN IER SECTION | | 

! I DftTA ! J 

t -.----- ---.- ..._...•.«.«.-«... j 

Figure 2-13. Concatenated Segment Format 

Notice that the concatenated segment is different for the two paths: 

• When accessing the real logical child below its physical parent, the 
concatenated segment will consist cf: 

1. The real logical child, which consists of: 

a. The concatenated key of the logical parent 

fc. The data cf the real logical child segment, if any 

2. Optionally, the logical parent segment itself. 

« When accessing the virtual logical child below the logical parent of 
the real logical child, the concatenated segment will consist of: 

1. The virtual logical child, which consists of: 

a. The concatenated key of the physical parent 

b. The data of the real logical child segment, if any 

2. Optionally, the physical parent segment itself. 

Note: The concatenated segment only exists in a logical data base. 

Because of the bidirectional virtual pairing, you can always define two 
logical data bases with one logical relationship. 

Figure 2-14 shews the twe logical data bases which can te defined using 
the related physical data bases cf Figure 2-12. 
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Figure 2-14. Phase 2 Logical Data Bases 



The above logical data bases will be used by our sample Fhase 2 
applicaticn programs. 

The exact rules for defining and processing logical data bases will be 
discussed in the following section. 

LOGICAL RELATIONSHIP RESIGN PULES 

In constructing lcgical relationships with EL/I, two sets of rules &ust 
be observed- One set fcr ccnstiucting the physical data bases and the 
second set for constructing lcgical data bases. It should be clear that 
a lcgical data base can be defined only if the underlying physical data 
bases are properly defined. 
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If necessary, multiple lcgical data bases can be defined for a given set 
cf logically related physical data bases- However, good practice is tc 
generate one logical data base for each physical root segment which 
contains cnly the segmenxs needed in your applications. 

l23isal_Child : 

1- A logical child segment must have one and only one physical parent 
segment and one and cnly one logical parent segment. 

2. A lcgical child segment is defined as a physical child segment in 
the physical data base of its physical parent, 

3- In its physical data base, a logical child segment cannot have 
another lcgical child as its immediate dependent, 

-CQicaj^Parent: 

1.. A logical parent segment can be defined at any level of a physical 
data tase including the rcct level. 

2. A logical parent segment can have one or multiple logical child 
segment types. 

3.. A segment in a physical data base cannot be defined as both a 
logical patent and a lcgical child. 

4. A lcgical parent segment can be defined in the same or a different 
physical data base as its logical child segment. 

F hys i c a J._ P a r e n t : 

1. A physical parent segirent cf a logical child cannot also be a 
lcgical child. This is the same as rule 3 for the logical child. 

Multiple lcgical relationships can be established within a single data 
base or betwesn two or acre data bases, as long as the above rules are 
obeyed. 

_____________ inin2_lcgical_Eaj:a J^ses 

1- The lcgical data base itself is always a single hierarchical 
structure. 

2. It must start with the root of a physical data base and can contain 
cnly segments defined in physical data bases. 

3- In following a hierarchical path, nc segments may te skipped. 

U. The logical child plus the destination parent is always presented as 
cne concatenated segment. 

5- The dependents cf a concatenated segment are: 

• The dependents cf the lcgical child 

• The lcgical or physical dependents of the destination parent 

The above dependents should not be intermixed, ncr should their 
relative order be changed. But you can start with either of them. 

• The physical parents up to the root of the destination parent 
in destination parent to root order 
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6. If physical parents of a destination parent are included, then you 
can also include their logical or physical dependents in their 
normal order. 

7, Any number of logical relationships can be used in a single 
hierarchical path in the logical data base up to the maximum of 15 
segment levels. 

No te s : 

1. Eecause of th<= virtual logical child concept, paths are 
bidirectional and can be intermixed and/or repeated in a single 
logical data base. 

2. All segments of related data bases are available as long as you 
follow the above rules- The same physical segment type could appear 
in several different paths if needed. 

Figure 2-15 shows some examples of logically related physical data bases 
and their associated logical data bases. It illustrates most of the 
above rules. This exaiple is ret representative for a typical DI/I 
application; it merely shows the different possible combinations. 
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Figure 2-15. Using Multiple Logical Relationships 
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PRCC1SSING LOGICALLY RELATED SEGMENTS 

P.eleting_Lc2icall2_Felated_ Segments 

Lojgic a^_Chil d : The logical child can be deleted via its physical parent 
path cr its logical parent path. If a logical child is deleted in 
either way, tfrsn all its dependents in the physical data base are 
deleted. If a concatenated segment is deleted in a logical data base, 
then cnly the logical child segment is deleted with its physical 
children. The destination parent is not deleted. In our subset, the 
logical child will be automatically deleted if either its physical cr 
logical parent is deleted. 

L53i£§i-.£§I§B* : * he logical parent can only be deleted via its physical 
parent~"path7 If the logical parent is deleted then all its children 
will be deleted including logical children. 

Fhy_sical_|arent: The physical parent car only be deleted via its 
physical parent path. If the physical patent is deleted, then all its 
children are deleted including logical children. 

I nsertins^Logically^R el ated_ Segments 

L2Sical^PJ3}rsical - Parent: Either parent type can only be inserted via 
its physical parent path. 

iS3i£§2-£liiii : Tne logical child can be inserted via either path, but 
the destination parent must already exist. 

^2£i§£i£2-if£2i£liiY_l!§l§i§^_§§3S§Ilts 

After a get hold call of the concatenated segment, fields in both the 
logical child and the destination parent can be changed before the 
replace call, except sequence fields, see Figure 2-16. 
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Figure 2-16. Replacing Fields in a Concatenated Segment 



LOGICAL RELATIONSHIPS IMPLEMENTATION TECHNIQUE 

The following pointers are used by DL/I, in our subset, to inclement 
logical relationships. These pointers are maintained in the segment 
prefix in the same way as the previously discussed physical child and 
physical twin jointers. again, a detailed comprehension of those 
pointers is net reguired at the moment, as we will give detailed 
guidelines for their selection in the implementation part of this 
chapter. 
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lcijnter£_Dsed_f or_logical_Relationshi£s in_HDAM^HIDAM 

i2aical_Far€nt_Pcint€r_JLP).: The logical parent pointer is within the 
prefix cf the logical child segment and points to the logical parent 
occurrence of that logical child. This pointer is always present and is 
never zero. Each logical child most have one and only one logical 
parent just as it has only one physical parent. 

!&ai£§i_£hiI<LIi£§£-.££i££§£ II£fl: The logical child first pointer is 

within the prefix of the logical parent and points to the first 
occurrence of its logical child segment. If a segment has several 
logical segment types, it contains one LCF pointer for each segirent 
type. If a logical parent has no lcgica 1 child occurrences, the 
corresponding LCF pointer is zero. The logical child first pointer is 
required. 

Logical^Child^Last^Pointer.JlCLJL: The logical child last pointer is 
within the prefix of the logical parent and points to the last 
occurrence of its logical child.. There is one LCL for each defined 
logical child segment type. The LCL pointer is optional. Its only use 
is to improve the performance of the logical child insert if nc seguence 
field is defined for the lcgical chain. See "Bole of the Virtual 
Logical Child" earlier in this chapter. 

L29i£al_3win_|grward_Pcinter_JITF]_: The lcgical twin forward pointer is 
within the prefix of the logical child segment and links all lcgical 
child occurrences of a particular logical parent. This pointer is 
required if any logical parent occurrence has more than one logical 
child occurrence. 

Losical_Twin_Back«ard_Pointer (LTB1: The logical twin backward pointer 

links lcgical twins but in the reverse order of the LTF. This pointer 
serves a complementary performance role as the physical twin backward 
pointer in deleting lcgical children. It should always be used -- 
together with the LCL -- if there are multiple occurrences of a logical 
child for any logical parent occurrence. 

P]lIsical_Parent_Pcinter (PJ?1: DL/I uses a physical parent pointer in 

the prefix of the logical child to locate that physical parent if the 
access was via the logical parent. This FP pointer is repeated up 
through the hierarchy tc the rcct. A physical parent pointer is also 
present in the lcgical parent if this is not a root segment. It then 
points to the physical parent of the logical parent, etc. You never 
need tc specify the inclusion of this pointer in the DBD. Dl/I will 
include it automatically if needed. 

5LZl_iICCNDA|X_IKriXES 

The secondary indexing capability of DL/I allows additional access paths 
to a data tase record. Secondary indexes provide: 

* A secondary processing seguence, enabling direct and/or sequential 
processing of data base records on non-root-key field values. These 
search fields can be located in the root segment or a dependent 
segment. 

• Automatic updating of the secondary index is always done, even if 
the program causing the change is not sensitive to the secondary 
index. 
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WHEN TC USE SECCHCAIY IKEEXES 

Secondary indexes should be mainly used when frequent, direct access to 
th« data base record is required en ncn-rcot-key fields- It should be 
realized that a secondary index incurs additional system cost in CPU and 
I/C time. If the information en which the secondary index is 
established is changed, then DI/I has to change the index entry. 

Especially for batch processing, you should compare the costs of full or 
partial data base scan plus a subsequent sort of the cutput versus the 
cost of using secondary indexes. For cnline data base processing, the 
choice is easier. Terminal user*s response requirements norirally dc not 
allow for full data base scans. 

SEGMENT TYPES INVOLVED IN SECONDARY INDEXES 

The segment types and associated terms involved in secondary indexes are 
(see Figure 2-17) : 

• Secondary Index 

A secondary index is comprised of an index pointer segment type 
defined in a secondary index data base that provides an alternate 
entry into a data base. 

• Index Pointer Segment 

A segment defined in a secondary index data base that certains the 
data and pointers used tc index the "index target segment." It 
controls the secondary processing sequence. 

• Index Target Segment 

The segment that is pointed to by an index pointer segment. In cur 
subset, it will always be a root segment. In that case, it is as if 
the search field "replaces" the original root segment sequence 
field. 

• Index Source Segment Type 

A segment that is the source from which a secondary index is 
created. 

• Secondary Processing Sequence 

The sequential order in which occurrences of an index target segment 
type are accessed through a secondary index. It is the order of the 
index pointer segment. 
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Figure 2-17. Segment Types Associated with a Secondary Index 

Although a secondary index can be used in programs which use only 
logical data bases, their implementation is strictly on the physical 
data base level. Figure 2-16 shows the physical data bases of our phase 
3 sample environment. The only difference from phase 2 is the Purchase 
Crder Numfcer secondary index data base. By utilizing this secondary 
index data b-ase, an application program can process the physical and/or 
logical Parts data base directly by purchase order number. 
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Figure 2-18. Phase 3 Physical Data Bases 

DESIGN PULES FOB SECONDARY INDEXING 

Several rules should be observed when designing basic secondary indexes: 

1. The index target segment should be a root segment in our subset. 

2. The index source segment and the index target segment must fce 
defined in the same physical DBD. They can be the same segment. 
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3. A logical child segment cannot be used as an index source segment. 
However, a dependent cf a logical child can be used as an index 
source segment. 

i). A secondary index can be used with a logical DBD, but the index 

target segment should be the root segment. Nothing additional need 
be specified in the logical DBD. 

JKFLEMENTATICB TECHNIQUE 

In discussing secondary indeies we have to distinguish between two 
different data base types. The first is the indexed data base. This 
data base contains the index source and index target segments. It is ar 
EC AM or EIDAM data base. The second is the seccndary. index data base, 
This data base contains the index pointer segments which contain 
pointers in their prefix to the index target segments. An IKDEX data 
base consists of a single KSCS. Figure 2-19 shows the physical format 
of the KSES logical record fcr the INDEX data base. 
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figure 2-19. Logical Record Fcrmat for the Index Pointer Segment 

The index pointer segment contains: 

• Delete flag (1 byte) controls the delete status of the index pointer 
segment. 

• Pointer to the index target segment (4 bytes) . 

• Search field (N bytes) contains a duplication of one to five index 
source segment fields which together define the secondary seguence. 

• Subseguence field JU bytes), optional. It is required in our subset 
if the search fields in the index pointer segments are non-unique. 
If specified, it contains the relative byte address of the index 
source segment. It is never used to access the index source 
segment. Its sole use is to provide a unique key for the KSDS 
logical record. In the DBDs, its field name must start with the 
three characters. 
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CP. FATING A SECONEARY INDEX 

Secondary indexes are created with the standard DL/I data base 
reorganization utilities, see Chapter 5- They can be created at initial 
data base load tine or later. Nc user programming is needed to create a 
secondary index. Also existing programs need not .be changed unless they 
want to use the secondary index. 

TATA EASE DESCRIPTION GENERATION 

After you finish the design of your data bases you must specify then tc 
DL/I. Ihis section gives the guidelines for the use of the DL/I data 
base definition language: the data base descripticn generation (DBDGEN). 
Again this section is divided into three subjects in concurrence with 
the thL^e phases: 

1. Easic DBDGEN fcr physical data bases 

2. EEDGEN for logical relationships 

3. DBDGEN foi secondary indexes 

For each data base to be used with DL/I, a data base description (DBD) 
must te generated. A EBD ccrsists of a set of DL/I-supplied macro 
instructions, coded by you to specify the data base characteristics you 
need. The DED is processed by an OS/VS assembler and the generated load 
module is stored by the linkage editor in the IMSVS.DBDLIB library for 
subsequent processing cf the data base. See Figure 2-20. 
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Figure 2-20. Data Base Description Generation (DBDGEN) 

Figure 2-21 shows the seguence cf the nacre statements in the DBD input 
deck. The DEEC 3 EN is executed by invoking a JCI cataloged procedure 
naired DBDGEN, which is available in IHSVS. EEOCLIE- 
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END Macro 
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type in the data base. //f rH iin 
The order is the heir- ^ X | LU MILU 
archical sequence. J fFI ELD 



Maximum: 255 




Required for index 
and/or logical relationships. 
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field for this segment. 
Maximum: 255 per segment type. 
1000 per data base. 



Required: 1 



Figure 2-21. EBDGEN Input Deck Structure 



EEEGEN CODING CONVENTIONS 

DBDGEN statements are Assembler language macro instructions and 
therefore, are subject to the rules contained in the publication 
OS^VS^DOS^VS^VMZilC Assembler, iangjiage, GC33-4010. 

In the generalized format shown in the following descriptions of the 
control statements, these syntax conventions apply: 

a. Words written in all capital letters must appear exactly as 
written- 

b. Words written in lcwercase letters are to be replaced by a 
user-specified value- Valid user-specified values are numeric 
values or one- to eight-character alphameric names. 

c. Tfce control cards are free form. Operation codes must begin 
after ccluira cce. Operands must fcllc« an operation code or 
prior operand. The first operand must be separated from the 
operation code by at least one blank column. Each operand 
should be separated from the previous operand by a comma. 
Operands may be continued on subseguent cards, but must start 
in card column sixteen on the continuation card. A nonblank 
character must be coded in column 72 if a continuation card 
follows. 

r i indicates optional operands. The operand enclcsed in 
1 | the brackets (for example, [ VL ]) may or may not be 
I | present, depending on whether or not the associated 

cpticn is desired. If more than one item is enclosed 

in brackets one or none may be coded. 



i j 



{ } indicates that a choice of an operand parameter must 
j } be made. One of the operand parameters from the 
{ } vertical stack within braces must be coded. 

,... indicates that more than one set of parameters may be 
designated in the same operand. 
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Jx a w£ le : 

j<- Column 1 |<- Operands - Column 16 
J, |<- Cperation - Column U 



/- 



Column 72 ->| 



DEC |NAME=BE1PARTS, 
|ACCESS=HIEAM 



EASIC EBEGEN CONTROL STATEMENTS FORMATS 



EBE_Sta£emeni 

This statement naoes the data base being described and specifies the 
organization used. There is only one in the input to DBDGEN. The 
format of the EBE nacre instruction is: 

/ i 



EEE 



INAME-dknamel 



, ACCESS^ 



SHI SAM 
IHEAK 



HIEAM 
INDEX 



frCSAMT 

L vsamJ 



|[ f RMNAME= (mod,anch,rbn, bytes) ] 
|[ ,PASSSD=JYES{] 

t . --j 



L eg e r d : 

EBE 

identifies this statement as the DEE control statement 

NAME=dfcname1 

dtnamel is the name of the DBD for this data base. This name can be 
from cne to eight alphameric characters. The first one should be an 
alphabetic character. It should be unigue for each EBE in your 
installations EL/I ervircntent. 

ACCESS= 

specifies the EI/I access method and the operating system access 
method tc be used fcr this data base. The value of the operand has 
the following meanings. 

SHISAH 

specifies a SKISAM data base with only a root segment with no 
prefix. It is a single VSAM KSDS. 
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BEAM 



specifies a HEAR data base. CSAM or VS&M can be selected as 
the operating system access method. VSAH is the default. 



HIEAH 



specifies the HIDAK main data base. VSAH ESDS is used as the 
operating system access method in our subset. 



INEEX 



specifies the INEEX data base of a HIDAM data base. VSAM KSBS 
is used as the operating system access method in our subset.. 

Note: 

• Guidelines for selecting the best access methods for a 
particular data base are provided under the topic "Selecting 
Eata Base Organization and OS/VS Access Methods" later in this 
chapter- 

• When VSAM is used, guidelines for the VSAM Access Method 
Services DEFINE command is produced in the DBDGEN output 
listing. These guidelines should be taken into account when 
defining the VSAM data set cluster. 

FMNAME= (mod, anch, rbn, fcytes) 

should be specified only if ACCESS= (HDAN,. . . ) 

nod 

specifies the lead nodule name of the randomizing module to be 
used for this data base. For mere details on randomizing 
modules see "HCAK Eandomizing Modules" in Chapter 7. 



anch 



rbn 



specifies the number of root anchor points desired in each 
control interval or block in the root addressable area of an 
REAM data base. The default value of this parameter is one. 
"anch" must be an unsigned decimal integer and must not exceed 
255. 

fchen a user randomizing routine produces an anchor point rumber 
in excess cf the rumber specified for this parameter, the 
anchor point used is the highest number in the control interval 
or block. When a randomizing routine produces an anchor point 
number of zero, EI/I uses anchor point one in the control 
interval cr block. 



specifies the maximum relative block number value that the user 
wishes to allow a randomizing module to produce for this data 
base. This value determines the number of control intervals or 
blocks in the root addressable area of an HEAM data base, 
"rbn" must be an unsigned decimal integer whose value dees not 
exceed 2**-1. If the randomizing module produces an rbn 
greater than this parameter, the highest control interval cr 
block in the rcct addressable area is used by Dl/I. If the 
randomizing module produces a block number of zero, control 
interval or block one is used by DL/I. 
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bytes 



specifies the maximum number of bytes of a data base record 
that car be stored into the root addressable area in a series 
of inserts unbroken by a call to another data base record. If 
this parameter is emitted, no limit is placed on the maximum 
number of bytes of a data base record that can be inserted into 
this data base's rcct segment addressable area, "bytes" must 
be an unsigned decimal integer whose value does not exceed 
2«*-1. 

PASSWI=YES 

causes Dl/I Cpen to use the KAME=operand for this DBD as the VSAM 
password when opening any data set for this data base- This 
parameter is only valid fci DBDs that use VSAM as the Operating 
System access method. The default is NO- 

When the user defines the VSAM data set Is) for this data base using the 
EFFINI statement cf OS/VS Access Method Services, the control level 
(CCKTRCLPW) or master level (MASTEFPW) password must be the same as the 
NAME for this EED. All data sets associated with this DBD must use the 
same password. For a description of the use and format of passwords for 
VSAM, see OS/VS Access Met he d Services. 

For the IMS/VS EB/CC (online) system, all VSAM CFENs will bypass 
password checking and thus avoid operator password prompting. For 
the IMS/VS DE Jbatch) system, VSAM password checking is performed. 
In the batch environment, operator password prompting will occur if 
PASSHD=NC is specified and the data set is password-protected with 
passwords not egual tc DBDNAME. 

The intended use of this facility is to allow you to prevent 
accidental access of IKS/VS data bases by non-IMS/VS prograos- 

2£ TA SE2_ Statement : 

This statement provides the link with the OS/VS data set and defines 
additional physical data set attributes. There is one for each DBD. 
ine fcrmat of the DATASET macro instruction is: 



/ 




DE 1=ddname1 



,EEVICE= 




,MODEL=<^ * 
11 

,SIZF=size 

[ ,FFSFC= (fbff,fspf) ] 
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Legend: 

DA1ASET 

identifies this statement as the DATASET control statement. 

EBl=ddname1 

identifies the ddname used in the JCL to execute DL/I application 
programs using the data base. It should be unique throughout the 
EL/I environment cf your installation. 

DEVICE= 

specifies the device type used for storage of this data set. 

MODEL* 

specifies the model cf the above device type. The valid 
combinations are: 

For 2305: 1 or 2 [2 is the default) 

lor 3330: 1 ce 11 |1 is the default) 

SIZE= 

specifies control interval size for VSAM data sets or blccksize for 
OSAM data sets. Fcr VSAM data sets the size must be: 

1. A multiple of 512 bytes 

2. If larger than €1S2, a multiple cf 2048 

3. Not larger than 3C;2C 

Fcr CSAM data sets the size must be an even number, net exceeding 
32K bytes, and nust net exceed the maximum non-keyed blocksize per 
track cf the direct access storage device used. 

Notes : 

1. As part of the Cl/blocksize you specify, DL/I and VSAM allocate 
space for systet fields. These are: 

« Free space anchor point 4 bytes 

• Anchor points (BEAM only) 4 bytes for each anchor 

point 

• VSAM control fields (ESDS) 7 bytes 

2. There is a free space element of eight bytes for each free 
space of 8 bytes cr mere. 

3. Guidelines for selecting Cl/blocksize , the bytes, anch and rbn 
parameters are F^ cv ided later in this chapter. 
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FBSPC=(fbff, fspf) 



specifies ho 
data base, 
specifies th 
will be left 
(where fbff= 
to 100 exc 
factor™ It 
interval cr 
The range of 
fspf is 0. 



v free space i 
The fbff is th 
at every nth c 

as free space 
n) . The range 
luding fbff=1. 
specifies the 
fclcck that is 

fspf is from 



s to be distributed in an HEAK or KIEAM 
e free block frequency factor, and it 
cntrol interval or block in this data set 
during data base load or reorganization 
of fbff includes all integer values from 
The fspf is the free space percentage 
minimum percentage of each control 
tc be left as free space in this data set 
C to 99. The default value for ftff and 



Notes: 



If the total of the percentage cf free space specified and any 
segment sire exceed the control interval or block size, a warning 
message is issued by EBDGEN that flags oversized segments. When 
loading oversized segments, the "fspf" specification is ignored and 
one control interval cr fclcck is used tc load each oversized 
segment- 
In general, it is net advantageous to use the FBSPC=parameter for 
HCAti. In most cases, ycu can better ccntrol the free space in BEAM 
with the size of the root addressable area (rfcn in the 
BMNAME=param€ter of the D8D statement) . This will be addressed 
later in this chapter under the topic "resign the Physical Data 
Structures," 



SJGM_S^atement 

This statement is used ence for each segment to be defined in the EEB. 
Its basic format is: 



SEGK I K*ME=segname1 

J[ ,PAEENT=<(segname2 r,SKGL"]) ) ] 
| L EBLEJ 

I ,EY.TES=bytes 

I (1\ 
|,F1B=<IE> 

I U'T 



L.e jge n d : 

SEGW 

identifies this statement as a SEGM control statement 

NAME*segname1 

specifies the name cf the segment as used by EL/I and the 
application progran. It is one to eight alphameric characters and 
each segment name should be unique in the EL/I environment cf your 
installation. 
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PAREN1= 



specifies the name of the physical parent of this segment. This 
keyword should be emitted for the rcct segment. The second 
parameter controls the physical child pointer (s) in the physical 
parent of this segment. 

SNGL specifies enly a physical child first pointer is used in this 
segments parent. 

DELE specifies both a physical child first and physical child last 
pointer are used in this segments parent. 

Recommendation : DBLE should be specified if: 

1« Average twin chain is more than 3 to 5 and freguent 
retrieve lasts, and/or 

2. Segment has no seguence field and freguent inserts are 
expected. 

EY1ES= 

specifies the length cf the data portion of the segment in bytes. 
This length does not include the prefix, which is established solely 
by CL/I. This length cannot exceed the maximum logical record 
length or ccntrcl interval/blcck size of the data set minus the 
space occupied by system fields. See the SIZE parameter cf the 
DATASET statement. It should be an even number. 

PT5= 

controls the physical twin pointer options. Specify: 

PTR=N1 (no twin pointer) if never more than one occurrence of this 

segment under its parent. No seguence field may be defined for 
the segment if PTR=NT is specified. 

P1R=1E (twin forward and backward pointers) if: 

• No seguence field is defined and freguent inserts are 
expected. 

« Retrieve last plus subseguent delete is freguently used. 

« The segment is a logical child. See phase 2. 

• It is the root segment of a HIDAM data base. 
PTR=1 (only twin forward pointer) in all ether cases. 
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FIELD_Statement 

This statement is used once for each field to fce defined in the DBD. 
The FIELD statements fellow the SEGM statement of the segment in which 
these fields belong. This statement is required for all sequence fields 
and fields which are tc be used in SSAs. Ihe basic format is: 

/ n 

1 
FIELD |NAME=(fldname1[ ,,SSEEQ]) 

I 

|,BYTES=fcytes 
1 ,STAFT=startpos 

t,TYFE=ili 

I 
i . j 



Le .gen d : 
EIILD 

identifies this statement as a FIELD control statement. 
NAME= 

f ldnamel 



SEQ 



specifies the name cf the field being defined within a segment 
type. Ihe name specified can be referred to by an application 
program in a CL/I call SSA. Duplicate field names must not be 
defined for the same segment type, fldnamel must be a one to 
eight character alphameric value. 



the presence of the keyword SEQ as a parameter of this operand 
identifies this field as a sequence field in the segment type. 
FIELD statements containing the keyword SEQ must be the first 
FIELD statements following a SEGM statement in a DBD generation 
input deck. As a general rule, a segment can have only one 
sequence field. If a sequence field is specified, then its 
value must he unique in cur subset for all segment occurrences 
under a given parent. 

A unique sequence field is optional for all dependent segment 
types. It must fce provided for the root segment of SHISAfl, 
HIDAM, and primary HIEAM INDEX data bases. 

When no sequence field is defined for a segment, new occurrences of 
the segment will be inserted at the end cf the physical twin chain. 
It is required, in our subset, that all parent segmerts which 
participate in logical relationships have unique sequence fields 
(except if PTE=NT is specified). This includes the physical and the 
logical parent and their parent segments up to their roots. 



EYTES= 



specifies the length of the field being defined in fcytes. 
maximum allowed is 255. 



The 
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STAR1= 



specifics the starting position of the field being defined in terms 
of bytes relative to the beginning of the segment. Maximum allowed 
value is 3C72C. startpes for the first byte of a segment is one. 
Overlapping, fields are permitted. 

IYFE= 

specifies the type cf data that is to be contained in this field* 
The value of the parameter specified for this operand indicates that 
cne of the following types of data will be contained in this -field: 

X = hexadecimal data 

P = packed decimal data 

C = alphameric data or a combination of types of data. 

It should be noted that all DL/I calls perform field 
comparisons on a fcyt€-by-byte binary basis. No check is made 
by DL/I to ensure that the data contained within a field is of 
the type specified by this operand, except when the defined 
field is irdexed. 

LCJiLD_S£atement 

This statement is used ence for each index or logical relation a segment 
har. It immediately follows the SEGM statement or FIELD statements of 
the segment involved. At this point we will only discuss its use in 
defining the primary index of a HIDhM data base. The basic format is: 

/ - — 1 

I 

ICHILD | NAKE= (segname, dbname) 
! 
|[ ,ETB=ISDX ] 

I 

IC ,IKDEX=fldname] 
I 

C-------------- ------------------------------------------------- -J 



The LCFILD statement is coded both in the INDEX data base and in the 
HIDAM main data base. Per the INDEX data base, code: 

NAME= (segname r dbname) 

segname is the name of the HIDAM root segment and dfcname is the name 
of the HIEAM data base as ceded in the DBD statement. 

INDEX=f ldr.ame 

fldname is the name of the sequence field of the HIDAM root segirent. 

For the HIDAM main data base, code: 

NAME= (segnan>e,£tnaoie) 

segname is the name cf the enly segment in the primary INDEX data 
base for this data base, and dbname is the name of that IKPEX data 
base. 
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PTR^INDX 



must fce coded as shown. It provides for the linkage with the INDEX 
data base. 



£§2<iEN_Statejeiit 

This statement must be included. It indicates the end of EED generation 

contrcl cards to define the EED. The format is: 

/ ■ ' 1 

/I I I 

| | DBDGEN I I 

III I 



EI23I.SH_ Statement 

This statement must be included. It sets a non-zero condition cede for 
link-edit if there are DBDGEN errors. The format is: 

/ ' -i 

/ I I I 

I IFINISB j | 

111 I 



This statement must be included. It indicates the end of the input 
statements to the OS/VS assembler. 

/ — ' - — -i 

/ I I I 

I I END | | 

111 I 

L * -,---------------- --J 

Execution^gf _DBDGEN_JJCI1 

DBDGEN must be run as a normal operating system job after IMS/VS System 
definition. System definition causes the DBDGEN procedure to be placed 
in the IMSVS.FBOCIIE library. To process a request for a DBDGEN, the 
DEE generation ccntrol cards must be created and appended to the 
following JCl (which invokes the DBDGEN procedure) : 

//DBDGEK JCE KSGIEVEL=1 
// EXEC DBDGEN, MBB= 
/-/C.SYSIN DD * 

DBD 

DAIASET 

SEGM 

FIELD DBD generation 

LCBILD control cards 

DEEGEK 

FINISH 

END 
/* 
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where keyword operand MBR = 

is the name cf the EED to fce generated. This name should be the 
same as the first rai€ specified for the NAME= keyword on the DBD 
statement. When a data base PCB (see PSBGEN later in this chapter) 
relates to this DBD generation, this operand value must be the nave 
used in the DBDNAME= operand on the data base PCB statement within a 
PSE generation. 

Note: If the defined EEE is for the primary INDEX data base cf an HIDAM 
data base, only one each of the SEGM, FIELD and LCHI1B statements is 
allowed. 

l£amjgles_Cf_£hysical_DBEs 

Figure 2-22 shows a sample HDAM data base which uses OSAM. This is our 
sample, EE1PARTS, included in IMSVS.PRIMESRC, Phase 1 PARTS data base. 
Job //SAME110 in IBSVS.EBIKEJCE can be used for its DEDGEN. 

Figure 2-23 shows the HIEAM version of the same PARTS data base. As cat 
be seen, two EBEs are required, one for the index data base and one £or 
the main data base. 

Notice that the HIDAM data bases use enly VSAM. The EBDs of Figure 2-23 

are not provided in IMSVS.PRIMESRC. However, they can be easily 

established if you were interested in using HIEAM for the PARTS data 
base. 
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71 



STOCK 
(SE1PSTOK) 



PART 
(SE1PART) 



PURCHASE 

ORDER 
(SE1PPUR) 



DESCRIPTION 
(SE1PGDSC) 



DESCRIPTION OF PA^TS DATAT.'.Si 
FCW PRIMES SAMPLE PROJECT PHASE 1 



DBD 



NAME=BE1PARTS, ACCESS = CHDAM, OSAM) , 
RMNAME=(DFSHDC4 0,4,80,50 0) 



DATASET DD1=DE1 PARTS, DEVICE = 33-30 , MODEL = 1 , SIZE = 2048 

PARTS- GENERAL INFORMATION (ROOT) 



SEGM 

FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 
FIELD 



NAME = SE1PART,BYTES = 8 0.,PTR = T 

START=01.BYTE5=08.TYPE=C . N AME = < FE 1PGPNR , SEQ) 

START=0 9,BYTES=13,TYPE=C,NAME=(FE1FGSNM) 

ST*RT=22,BYTES=0S,TYPE=C,NAME=CFE1PGNEW) 

START=30,BYTES=0S,TYPE=C.NAME=(rElPGOLD> 

START=38.BYTES=08,tYPE=C,NAME=<FElPGEQV) 

START=46,BYTES=08,TYPE=C,NAME=(FE1PGUNT) 

START=5«,BYTES=08.TYPE=C,NANE=CFE1PGPRI) 

START=62,BYTES=08,TYPE=C,NAME=CFE1PGDIM) 



PARTS- STOCK INFORMATION 



SEGM 

FIELD 

FIELD 

FIELD 

FIELD 

FIELD 



SEGM 

FIELD 

FIELD 

FIELD 

FIELD 

FIELD 

FIELD 



NAME=SE1PST0K, BYTES =40, PARENT=((SE1PART,SNGL)),PTR=T 
START=0I,BYTE5=1S , TYPE =C , NAME =( FE 1 P SL OC , SEQ) 
START=13,BYTES=06,TYPE=C,NAME=(FE1PSDAT) 
5TART=19,BYTES=0 6.TYPE=C,NANE=(FEiPSCNT) 
START = 2.5,3YTES = 06,TYPE = C,NAME=CFE1PSISS) 
START=31,BYTES=0 6,TYPE=C,NAME=CFE1PSREC) 

PARTS- PURCHASE ORDER INFORMATION 

NAME=SE1PPUR,BYTES=6 0, PARENTS CSElPART,SNGL)),PTR=T 

START , 01,BYTES=08.TYPE=C,NAME=(FE1PPONR,SEQ) 
START=09,BYTES=06,TYPE=C,NAME=(FE1PPODT) 
START=15,BYTES=2 0,TYPE=C,NAME=(FE1PPOSU) 
START=35,BYTES=06,TYPE=C,NAME=(FE1PPQOD) 
START=41,BYTES=0 6,TYPE=C,NAME=CFE1PPQRD) 
START=4 7,BYTcS=0 6,TYPE=C,NAME=(FElPPDDT) 



SEGM 
FIELD 

DBDGEN 

FINISH 

END 



PARTS- GENERAL DESCRIPTION 



NAME=SE1PGDSC, BYTES =80, PARENT: ((SE1P ART, SNGL ) ) , PTR=NT 
START = 01,BYTES = 5 0,TYPE = C,.NAME=(FE1PGLNM) 



Figure 2-22. Phase 1 EDAM PARTS DBD, BE1PAPTS 
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HIOAM PARTS DBDt 



HIDAM PRIMARY INDEX DATA BASE 



HIOAM MAIN DATA BASE 



PARTNUMER 
(SE1PINDX) 












PART 
(SE1PARD 


























































s* "I 




^ 


y" 








S 






STOCK 

(SE1PSTOK) 




PURCHASE 
ORDER 
(SE1PPUR) 




DESCRIPTION 

jSEIPGDSa 



DESCRIPTION OF PRIMARY INDEX 
INTO THE PARTS HIDAM DATABASE 



D80 NAME »BE1PIN0X, ACCESS" ( INOEX.VSAM) 

DATASET DOl'DE IP INDX, DEVICE » 3330, MODEL' LSI ZE»20<i8 

SESM NAME'SEIPINDX.BYTES'8 

L CHI ID NAME ■< SE1 PART, BE 1 PARTS) . INDEX' ( FE 1 PGPNR ) 

FIELD NAME '(FEIINDX.SEQLBYTES'S, START" I 

DBDGEN 
FINISH 
END 



DESCRIPTION OF PARTS DATABASE 
FOR FRIMER SAMPLE FSOJECT FHASE 1 



DBD NAME»BE1PARTS.ACC6SS=HIDAM 

OATASET DDl»DElPARTS,DEVICE»33 30,MODEL'l,SIZE»2 0<i8 

PARTS- GENERAL INFORMATION (ROOT) 



SEGN NAME »SE1 PART, BYTES -SO. PTR'TB 

LCHILD NAME»(SE1PINDX,BE1PINDX),PTR»INDX 

FIELD START = 0L6YTES*08,TYPE«C.NAM£=CFE1PGPNR.SEQ> 



DBDGEN 

FINISH 

END 



Figure 2-23. Sample DBDs for a HIDAM Data Base 

DBDGEN FOB GSAM 

A GSAM DBD contains the following statements: 



/ 



DBD 

DA1ASET 



DBDGEN 
FINISH 
END 



! 



I 
I 

JNAME=dbname,ACCESS= (GSAM r BSAM) 

! DDl=ddname,BECFM=recfra 

l[ ,RECORD=lrecl] 

|[ ,SIZE=blksize] 

I 



NAME=dbname 

specifies the name of this data base. 

DDl=ddname 

specifies the name of the DD statement used in the JCL when 
accessing this data base. 
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RECFM=recfm 

specifies the format of the records in the dataset. The record 
format is specified using the characters defined below: 

F -- the records are of fixed length, 

FB — the records are of fixed length and are blocked. 

V — the records are of variable length. 

VB -- the records are variable length and are blocked. 

F.ECOBD=lrecl 

specifies the size of a logical record for a fixed length record and 
the maximum logical reccrd length foi a variable length record. 

SIZE=blksize 

specifies the blocksize of the GSAM dataset for fixed length records 
or the maximui blccksize for variable length records. 

The record and size parameters can also be specified via the JCI. Tvo 
sample GSAM DBDs, B00IKP01 and E00OUT01 are included in IMSVS.PRIMESRC, 
Their DBEGENs can te executed with job //SAMP010 in IflSVS. PRIMEJOB. 
Furthermore, these DBDs can be used by your own application programs if 
the file attributes are the same. 

EBDGEN FOB LOGICAL RELATIONSHIPS 

To support the logical relationship function, DBDGEN is extended in two 
ways: 

• Additional control statements and parameters can be specified in the 
physical DBD. 

• A different type of DEC is created for the definition of the logical 
daxa base. However, this is done with an extension of the existing 
ccntrol statements- 

The DBDGEN process itself is unchanged- 
Cod ing_a_Logical_Relationshig_in_^ 
The following control statements are unchanged: 

DBD 

FIELD 

DBDGEN 

FINISH 

END 

Note: Additional restrictions exist for the length of a seguence field 
of a segment involved in a logical relationship. See the section 
"Restrictions" for the Data Ease Frefix Resolution Utility in Chapter 5, 
"Data Ease R€organizaticn/Lcad Processing." 
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The following statenents are extended: 

SEGH 
ICHILD 

Logical Child; For each defined logical child, you need to code two 
SEGM~"stateients. Cne within its physical parent's DBD and cne within 
its lcgical parent's DBD. The format under the physical parent EED, 
that is, fcr the real logical child is: 



/ 



SEGM 



I 

| NAKE^segnamel 

!,PARSNT= 

I [ {segname2, SNGL) , (segname3,P,dtnaB€2) ) 

1 DBLE 

|,B*TES=byt€S 

I (I ] r . .i 



i ,ptr= (lp,<tb 
1 Ut. 

1 

|,fiGLES=VVV 

! 



LIB 



NAME=segnarae1 

segnamel is the name of the logical child segment. 

PAEEN1- 

segname2 is the name cf the physical parent segment of this logical 
child. 

SNGL and DELE have the same meaning as before. 

segnan€3 is the naae cf the lcgical parent of this logical child- P 
should he specified as shown in our subset, it defines the logical 
paren-t concatenated key to be stored with the segaent in physical 
storage. dfcnao€2 is the DBD name of the logical parent's data base. 

EYTES^bytes 

has the same meaning as before. Notice however that the lcgical 
child always ccntains the logical parent's concatenated key in the 
first n fcytes, and its length must be included here. 



PTR= 



IP must be specified as shown in our subset. It provides 
fcr a pcinter tc the lcgical parent in the prefix 
of the ICHIIt. 

T the same considerations as before apply. 

TE it is highly recommended that you specify TE 

if there are, on the average, more than 3 to 5 logical 
child occurrences per physical parent. 

NT should be specified if never more than one occurrence 
of this segment per parent 
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L2 if specified, only a logical twin forward pointer 
is used fci the logical twin chain. 

LTB if specified, both a logical twin forward and backward 
pointer are used for the logical twin chain. 
This should be selected whenever there are, on the 
average, more than 2 to 3 logical child occurrences 
for a logical parent, 

BOLES = VVV 

should be specified as shewn for our subset. 

The format under the logical parent, that is, for the virtual logical 
child is: 

/ - - - i 

/ I I I 

SEGM J KJME=virtchild | 

l,PARENI=segname2 j 

| ,SOOBCE= I (segname3, D, dtnamel) ) f 

|,PTR=PAIRED | 



Legend: 

NAME=virtchild 

virtchild is the name cf the virtual logical chiid. Remember that 
the virtual logical child dees not actually exist. Its only purpose 
is to define the logical child as seen from the logical path. It 
can be followed by a sequence fiel d which controls the sequence of 
the logical child segment when accessed via its logical path, that 
is, the logical twin chain sequence. 

PARENT=segname2 

segname2 is the name of the logical parent, that is, the physical 
parent of the virtual logical child. 

SOUBCE= ( (segnam€3,E,dtnam€ t) ) 

segname3 is the name of the real logical child and dbnamel is the 
DBD name of the data base which contains that logical child. D 
should be specified ir cur subset, it defines that both key and data 
of the segment are accessible by the PSE. 

PTR=PAIRZE 

Should be specified as shewn. It defines this segment as a virtual 
logical child. 

Phyjsical_and_Iogical_ Parent : Cne additional parameter must be specified 
in the SEGM statement of both the physical and the logical parent: 

SEGM flftKE=.. ..« ,BUIES=ELV 
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For each logical child segment type, an 1CHILD statement oust be added 
immediately following the SEGM and/or FIELD statement of the logical 
parent. Its tasic format is: 

/ 1 

/ 1 

ILCHILD |NAME= (segnamel ,dbname) 

,PTR=/SNGL 
CBIE 

,PAIR=virtchild 



Lecj € nd : 

NAME=(s€gnam€l,dknane) 

segnamet is - the segment name of the logical child in the DEC whose 
name is dbname. 

PTB= SNGL 

riil" 

SNGL specifies that there will be only a logical child first pointer 
in the prefix of the logical parent- DELE specifies that both a 
logical child first and last pointer will appear in the logical 
Farent- 

Recom mend at ions: 

Specify SNGL if a sequence field is defined for the virtual 
logical child and command code L (retrieve last) is rarely or 
never used to access the logical child. 

Specify DELE if re sequence field is defined for the virtual 
logical child and/or command code L is heavily used and there 
are, on the average, more than three occurrences of virtual 
children withic a legical parent. 

PAIE=virtchild 

virtchili specifies the name of the virtual logical child which must 
te defined in tfce same D3D {see previous SEGM statement) - 

IX^lfilSS of Physical DBDs jjith Logical Relationships 

Figure 2-24 shews the twe lcgically related physical DBDs of our Fhase 2 
sample environment- Only those DBD statements are shown which are 
essential to the legical relationship function. Compare these DEDs with 
the ones cf Figure 2-22 and 2-23. The DEDs of Figure 2-24 are also 
included in IMSVS.PRIMESRC. Their DBDGENs can be performed with jot 
//SAMP210 in IM3VS.PRIMEJ0B- 
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DBD=BE2PARTS 



LOGICAL. 
PARENT' 




DBD=BE20RDER 



CUSTOMER 

ORDER 
(SE20RDER) 



VIRTUAL. 
LOGICAL CHILD' 



| (SE2PAROR) | 

L J 



DESCRIPTION OF PARTS DATABASE 
FCR PRIMER SAMPLE PROJECT PHASE 2 



DSD 



NAME=BE2PARTS,ACCESS=(HDAM,VSAM), 
RMNAME = (DFSHDC<iO,<i,»0,5(IO) 



DATASET DD1=DE2PARTS,DEVICE = 3330, MODEL =1,SIZE = 20<.8 

PARTS- GENERAL INFORMATION (ROOT) 

5EGM NAME=SE1PART,BYTES=80,PTR=T,RULE5=PLV 

K CHILD NANE=(SE20DETL,BE20RDERI.PAIR=SE2PARCP,PTP=OBLE 
FIELD STAPT = 01,BYTES=08,TYPE=C,N. , ME = (FEIPEF(W,5EQ) 



VIRTUAL LOGICAL CHILD 

(CONNECTION FROM CUSTOMER-ORDER DB) 

► SEGM NAME = SE2PAR0R, PARENT =SE1 PART, PTR = P AIR ED, 
SOURCES (SE20DETL,D,BE20RDER)) 
FIELD STAOT = 01,E^YTES=Ofc,N.\ME = f FE20DKt;R,SEQ) 
DEFINES SEQUENCE OF LT-. CHAIN 



r 



•physical 
'parent 



ORDER LINE 
(SE20DETL) 



.(REAL) 
'LOGICAL CHILD 



DESCRIPTION OF ORDER DATABASE 
FOR PRIMER SAMPLE PROJECT PHASE 2 



DBD NAME=BE20RDER.ACCESS=HIDAH 

DATASET DD1=DE20RDER,DEVICE=3330, MODEL =1 , SIZE = 20<.« 

CUSTOMER-ORDER GENERAL INFORMATION 



SEGM NAME=SE20R0ER,BYTES=60,PTR=TB,RULES=PLV 
LCHILD NAME=<SE20RDRX,6E20RDRX),PTR=IU3X 



FIELD STAPT=01 .BYTES=06 ,TYPE=C ,NAME=I FE20GPEF ,SEQ ) 



CUSTOMER-ORDER DETAIL INFORMATION 



► SEGM 



NAME=SE20DETL,BYT£S=30, 
PARENTS (SE20RDER,DBIE).(SE1PART,P,»E2PARTS>>, 
PTR=<TB,LTB,LP),RULES=VVV 
FIELD STAPT = 0<>,BYTES=03,TrPE=C,UAME=(FE2ODLHR,SEQI 



DBDGEN 
FINISH 
END 



DBDGEN 
FINISH 
END 



Figure 2-2*». Phase 2 Physical DBDs 

Co£inc|_A_!;0(2ical_EBD 

A logical DEI r tased on existing physical DBDs, defines a new view of 
logically related data bases- This view is always a hierarchical data 
structure. Following are the control statements used and their formats: 

JEJLL-S t at emen t : 

/ -i 

/ \ \ I 

I |DED |NAME=dtdname1,ACCESS=LCGICAI | 

III i 

NAKE=dbdn?me1 

dhdnamel is the name of this logical DEE. It must te unique in your 
installation and the same name as specified in the KEF operand of 
DBDGEHo 

ACCESS=LOGICAL 

defines this EED as a logical DBD 
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DATASES^ Statement: 



/ 



IDA1ASET IICGICAI 
I I 



This statement must be coded as shown. 



SEG|L Statement: 



The segments in a logical EEC must be coded in hierarchical sequence 
following the rules for defining logical data bases as presented earlier 
in this chapter. 



/ 



I 
SEGK 1 NAKI=segname1 

|[ ,PAFENT=segname2] 

! ,SCUSCE= I (segname3, E,d enamel) 

I [ , Jsegname4,D,dbname2) j) 



NAME=segname1 

segnamel is the name cf this segment. 

PAEENT=segname2 

segname2 specifies the name of the parent of this segment. segname2 
must be defined previously in this EEC. This parameter should be 
omitted fcr the rcct segaent. 

SOURCE* ( (segname3,D,dbname1)[ , (segnameU ,D,dbname2) ]) 

This parameter specifies the source (s) of the defined segment. The 
long form is only applicable to concatenated segments. 

Non-concatenated segments: 

segnameS defines the source segment. The source segment must 
be defined in a physical DED whose name is dtnamel. 

Concatenated secments: 

• segnameS defines the logical child as -defined in the physical 
DBD. If the preceding parent segment is the physical parent, 
then the name cf the legical child must be coded. If the 
preceding parent is the logical parent, then the name of the 
virtual legical child must be ceded. 

• dbname 1 defines the physical DBD in which segnameS is defined. 

• segname<J defines the destination parent. 

• dbname2 defines the physical EEE name of the destination 
parent. 

Note: The destination parent (segnameU) should be included in the 
concatenated segment only if your application has a real need for it. 
If it is not specified, EI/I does not need to access the destination 
parent except fcr insert and delete calls. 
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252GIN x _FINISH_and_ZNC_State S ,ents_ 

These should be coded as before. 

Note that no ICHILD or l-IIIE statements are allowed in a logical DBD 

E£att£l§_Of_L^gical_EBI)s 

Figure 2-25 shows the logical EEE for our Phase 2 PABTS data base, 

BE2LPAET. 





PART 
(SE1PART) 






































s 


C 




f 




X 




^ 




y 




C ^ 


S 


STOCK 
(SE1PSTOK) 


/ 




PURCHASE 

ORDER 
(SE1PPUR) 


S 




DESCRIPTION 
(SE1PGDSC) 


/ 




ORDER CUSTOMER 
LINE ORDER 
(SE20RDRS) 

1 


/ 


























S 


S 






SHIPMENT 
(SE20SHIP) 







DATABASE DESCRIPTION OF THE COMBINED 
PARTS/ORDER DATABASE (LOGICAL) 

DBD NAME=BE2LPART,ACCESS=L0GICAL 

DATASET LOGICAL 



SEGM 
SEGM 

SEGM 

SEGM 

SEGM 

SEGM 

DBDGEN 
FINISH 
END 

Figure 2-25. Phase 2 logical EED for the PfiRTS Data Base 



NAME=SE1PART,S0URCE=C(SE1PART,D,BE2PARTS)) 

NAME =SE1PST0K, SOURCE =( (SE1PST0K,D,BE2PARTS)), 

PARENT=SE1PART 

NAME=SE1PPUR,S0URCE=( CSE1PPUR,D,BE2PARTS)), 

PARENT=SE1PART 

NAME = SE1PGDSC, SOURCE = ( ( SE 1 PGDSC , D , BE 2 PAR TS ) ) , 

PARENT=SE1PART 

NAME=SE20RDRS, 

SOU RCE=((SE2PAROR,D,BE2 PARTS), (SE20RDER,D,BE20RDER)), 

PARENT=SE1PART 

NAME=SE20SHIP,S0URCE=(CSE20SHIP,D,BE20RDER)), 

PARENT=SE20RDRS 
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Figure 2-26 shews the logical DBD for our Phase 2 CUSTOMER C5EEES data 
base, BE2LCRDE. 



Z 



ORDER 
LINE 



PART 



(SE20PART) 

L 



STOCK 
(SE1PSTOK) 



PURCHASE 

ORDER 
(SE1PPUR) 



CUSTOMER 

ORDER 
(SE20RDER) 



SHIPMENT 
(SE20SHIP) 



DESCRIPTION 
(SE1PGDSC) 



DATABASE DESCRIPTION OF THE COMBINED 
ORDER/PARTS DATABASE (LOGICAL) 



DBD NAME=BE2LORDR , ACC ESS = LOG I C A L 
DATASET LOGICAL 



SEGM 
SEGM 



SEGM 

SEGM 

SEGM 

SEGM 

DBDGEN 
FINISH 
END 



NAME=SE20RDER,S0URCE=CCSE20RDER,D,BE20RDER)) 

NAME=SE20PART, 

S0URCE=((SE20DETL,D,BE20RDER),(SE1PART,D,BE2PARTS)), 

PARENT=SE20RDER 

NAME=SE1PST0K,S0URCE=((SE1PST0K,D,BE2PARTS)), 

PARENT=SE20PART 

NAME=SE1PPUR,S0URCE=((SE1PPUR,D,BE2PARTS)), 

PARENT=SE20PART 

NANE=SE1PGDSC,S0URCE=C(SE1PGDSC,D,BE2PARTS)), 

PARENT=SE20PART 

NAME=SE20SHIP,S0URCE=C(SE20SHIP,D,3E20RDER)), 

PARENT=SE20RDER 



Figure 2-26. Phase 2 Logical DBD for the CUSTOMER ORDERS Data Base 

The logical CEDs of Figure 2-25 and 2-26 are included in IMSVS.PRIMESRC. 
Their DEDGZNs can fce performed with job //SAMP210 in IMSVS. PRIKEJCE. 

DBDGENS FOR SECONDARE INDEXES 

To support the secondary index function, the DBDGEN process is extended. 
We differentiate between the index target DED and the index pointer CBE. 
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CODING AN INDEX 1ABGET EATA EASE 

The control statements extended fcr the secondary index function are: 

SEGM 

FIELD 
LCHILE 

A new ccntrol statement is added: 

XDEID 
The following control statements are unchanged: 

DED 

EATASET 

SEGK 

EEEGEN 

FINISH 

ENE 

Codi£3_iJbi_l£^5^_l§rset_S€3ff€nt 



r 



XDFLD 



LCHILD 



NAME= 



NAME= . ... 



c 



FIELD 



SEGM 



NAME= . . . 



NAME= . 



Figure 2-27. DBE Statements for Index Target Segment 



SEGK_£tatement 

SEGM 

is a standard SEGM statement fcr the root segment. It has no 
additional parameter for secondary indexes. It is recognized as an 
index target segment because of the following LCHILE and XDFLD 
statements. 

LCHILD Statement 



| I LCHILE |NAflE= (segname 1 ,dbname) , PTE=IN EX 

I $ I 

LCHILE 

This statement provides the link to the index data base. 
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NAME= (segnamel ,dbname) 

segnamel is the name cf the index pointer segment as defined in the 
INDEX data base, dfcname is the name cf the EED for the IKDEX data 
base. 

PTK=INEX 

identifies the LCHILD statement as an index type. 



Note: There are three types cf 
index of an HIEAM data case, on 
under its logical parent, and o 
segment. All three types cculd 
data base. There could be mult 
both logical relationships and 
the LCHILD statements should be 
secondary indexes are tc be def 
must immediately follow its cor 

XDFLD Statement 



LCHILD statements; one for the primary 
e for the definition of a logical child 
ne for the definition of the index target 

occur below the root segment of a H1DAM 
iple occurrences of LCHILD statements for 
secondary indexes. The relative order of 

as described above. If multiple 
ined for cne segment, the XDFID statement 
responding LCHILE statement. 



IXBFIE |NAKE=fldname 

1 j ,SEG£EKT=segnarae 

| |,SHCH=list1 

J IC ,SUESEC=/SXname] 



XDFLD 

This statement defines the index source fields, that is, the fields 
used for the secondary index access. It defines the source data for 
the index search field in the INEEX data base. 

NAME=fidname 

specifies the name cf the secondary index field, fldname ic a 
normal field name which can be used in the SSA for the call which 
reguests secondary index access. It must be unique among all field 
names specified for the abcve index target segment. 

SEGMENT =segna ma 

specifies the index source segment for this secondary index 
relationship. segrane irust be the name of a subsequently defined 
segment type, which is hierarchically below the index target segment 
type or it can be the name of the index target segment type itself. 
The segment name specified must not be a logical child segment. If 
this operand Is emitted, the index target segment type is assumed to 
be the index source segment. 

SBCH=list1 

specifies which field or fields cf the index source segment are to 
be used as the search field cf a secondary index, listl must be a 
list of one to five field names defined in the index source segment 
type by FIELD statenents. Ir two or more names are included* they 
must be separated by commas and enclosed in parentheses. The 
sequence cf names in the list is the sequence in which the field 
values will be concatenated in the index pointer segment search 
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field. The sum of the lengths of the participating fields forms the 
length of this XLF1D as used in SSAs. 

SOBSECVSXname 

This parameter oust te ceded if duplicate index pointer segments may 
occur. /SXname must be the same as coded in the corresponding field 
statement of the index source segment. (See the next section, 
"Coding the Index Source Segment.") 

Coding_the Index Source Segcent 

/ i I 1 

| IFIELD | NAME=/SXname,... | 

— ! " I T I 

/ I I I I 

I IFIELD |NAME=... | J 

i I 

/ I I I I 
| JSEGM |KAKI=... | J 

I I I 1 

t--- ........ ..... .- ..... j 

Figure 2-28. EEC Statements fcr Index Source Segment 

SEGM Statement 

SEGM 

This is a standard SEGM statement with no additional parameters. It 
is reccgnized as an index source segment because it is defined in a 
preceding XDFLD statement under the index target segment. It must 
not be a logical cfcild. 

15JiI-Stat€m€nt 

/ - -i 

/ I I ! 

| jFI*LD I NAME=/SXname,BYTES=U,START=1 | 

II! I 

i......... ...-. ............. . . . .j 



FIELD 



In addition tc the ncriral FIELD statements for the segment, one 
extra FIELD statement can be added. Its name must start with /sx. 
This field is required whenever duplicate XDJLDs may occur in the 
data base.. Although the values of EYTFS and START are disregarded, 
they must be coded. Ncte that the /SXname field is called a "system 
related field." It provides control information to DL/I and it is 
completely transparent tc the application program. Example: In our 
purchase order, secondary index, there may well occur multiple index 
pointer segments with the same purchase order number (that is, for 
the different parts ordered in one purchase order). Therefore, this 
function is required in that data base, otherwise duplicate KSDS 
keys would occur. 
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CGDING A SECONDARY INDEX DBD 

The following statements are used in a secondary index DBD: 

DEC 

DA1ASET 

SEGM 

LCHILD 

FIELD 

DBDGEN 

FINISH 

END 



5§2-Stategent 

/ , ^ 

/ I I I 

| | DBD |KABI=dtname1 | 

| t 1 ,ACCESS= (INDEX[,DCSCCMP]) ! 

Ill ! 

c ---» J 



NAME=dbname1 

specifies the name cf the secondary index data base. It should be 
the name specified ty the MBR keyword of DBDGEN, 

ACCESS=(INDEX(,DCSCCMF]) 

INDEX identifies this as an index data base. DOSCOMP is an optional 
parameter and should be specified if this data base was created with 
EOS DL/I. 

PiTiSJT_Statejtent 

/ "» 

/I I I 

| jDATASET |DDl=ddname1,DEVICE=device,MCDEL=model | 

I | |,SIZE=size | 

I S \ I 

1---,..-..-.---.-------------------------.-------..--------...-.-^ 



The values specified for the DD1, DEVICE and MODEL parameters are 
exactly the same as discussed under "Easic CBEGEN Control Statements 
Formats," 

SIZE=si2e 

specifies the control interval size of the KSDS for the INDEX data 
base. This value must conform to the rules specified under "Basic 
DEDGEN Control Statements Formats," See also Selecting Cl/block 
sizes later in this chapter. 

SEGM_Statement 

/ * - T 

/ I I I 

| I SEGM lNAKE=segname1,EYTES*bytes | 

! ! > I 

t -. ------------ -j 
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Only one SEGM statement with its associated LCHILD and flELD statements 
is required for th€ secondary irdex data base, 

NAME=segname 1 

specifies the name of the segment being defined. Although ret used 
ty application programs ir the subset, it should be unique among the 
segment names in your installation. 

BYTES=bytes 

specifies the length cf the data portion of the index pointer 
segment. If a /SXnaoe field is defined in the SUESEQ parameter of 
the corresponding XDELD statement, then its length (4 bytes) must be 
included here. 



LCHILD .Statement 

/ * - - i 



LCHILC | NAME= (segn<*me1,dbnarae) 
| ,ETE=SKGI 
|,INDEX=fldname 



i .. . ..-._-----.- .. — ....... ., .-..j 



NAME= (segname 1, dtname) 

specifies the segment name of the index target segment and the name 
of the DBD in which it is defined. 

PTF=£NGL 

specifies that a iJ-tyte direct byte address pointer in the prefix of 
the index pointer segment will be used. It will point to the index 
target segment. 

INDEX=fldname 

specifies the fieldname of the indexed field. This fldname must be 
specified as the came cf an XDFLD below the index target segment. 



HJH-Statement 

/ 

I 

I FIELD 



/ 



|NAME= (fldname1,SEC) 
| ,B*TES=byt€S 
1,S!IART=T 



Cnly cne FIELE statement shculd be coded for each SEGM statement. 

NAME= (fldname 1, SEQ) 

fldnamel is the name of this field. It is not used by the 
application progras ir. cur subset. However, it should be specified 
following the rules of ether fieldnames. SEQ defines this ae a 
urigue sequence field and must be specified as shown in our subset. 
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BY3ES=bytes 



specifies the length of the field. This is the length of the search 

field as defined in the XDFID statement, pins four if tlie /SX field 

is included. It also is the length of the key for the KSDS* In our 
subset, it is equal tc the length of the preceding segment- 



€ 

SE 



The DBDGEN, FINISH and END statements shculd be coded as before, Figur 
2-29 shows the physical EABTS DBD (EE3FAETS) and its associated PORCKAS* 
CEDES secondary index DBD (BE3PSID1) for our Phase 3 sample environment.. 
These DBDs, togexher with the Phase 3 CCSTOMER ORDERS EEE (BE3CEEE5) are 
included in IKSVS. EFIJiESEC. Their DBDGENs can te performed with job 
//SAMP310 in IMSVS.PRIMEJOB. 



DBD=BE3PSID1 



DBD=BE3PARTS 



INDEX 
POINTER | 
SEGMENT 



SE3PSIDI 















SE1PART 




~— ~ > 


--» 




INDEX _. 
SOURCE W+ 
SEGMENT V 


SE1PPUR 



INDEX 
(TARGET 
SEGMENT 



DESCRIPTION OF SECONDARY INDEX 

INTO THE PARTS DATABASE 

FOR PRIMER SAMPLE PROJECT PHASE 3 



DESCRIPTION OF PARTS DATABASE 
FOR PRIMER SAMPLE PROJECT PHASE 3 



DBD NAME-BE3PSIDl,ACCESS«INDEX 

DATASET DD1=DE3P5ID1,DEVICE=3330, MODEL = 1,5IZE=Z<HB 

SEOM NAME=SEJPSID1,BYTES=12 
► l CHILD NAME=<SE1PART,BE3PARTS>, IN0EX=FE3PSID1 ,PTR=SNGL 
FIELD NAME- < FE3PSX01 . SEO) . BYTES" 12, START=0i 

DBDGEN 
FINISH 
END 



DBD NAME=BE3PARTS. ACCESS: (HDAM.VSAM), 
RMNAME = (DFSHDC40.«,8(I,50 0) 

DATASET DDI = DE3PARTS,DEVICE=3330. MODEL = I.SIZE=20<S8 

PARTS- GENERAL INFORMATION (ROOT) 

SEOM NAME=SEIPART,BYTES=80,PTR=T.RULES=PLV 

FIELD START=0I. BYTES* 08. TYPE=C, NAME =<FE1PGPNR,SEQ> 



Figure 2-29. Phase 3 Physical DBDs 



CONNECTION TO CUSTOMER-ORDER DB . : 
LCHILD NAME=<SE200ETL.BE30RDER),PAIR=SE2PAR0R.PTR=DBLE 
CONNECTION WITH 2ND INDEX i 
> LCHILD NAME=CSE3PSID1.BE3PSID1),PTR=INDX 
►XDFLD NAME=FE3PSID1, SEGMENT =SE1PPUR,SRCH=FE1PP0NR, 
SUBSEI)=/SXPPUR 



SEOM 
FIELD 



DBDGEN 
FINISH 
ENO 



PARTS- PURCHASE ORDER INFORMATION 



NAME=SE1PPUR,BYTES=6 0, PARENTS (SE1PART,SNGL)),PTR=T 

START = (H.BYT£S = 08. TYPE =C.NAME=.<FE1PP0NR. SEO > 



START=OI,BYTES=CK.TYPE=C,NAME=/SXPPUR 
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IIOGEAM iHCIFICAlICN ELCC* GJUJATICN JPSJGjN)_ 

For each program which uses a ri/I data base, a program specification 
block (PSB) is needed. Although cue PSB can serve different batch 
application progfams, it is recommended, for integrity purposes, that 
each program have its cwn FSE. In the online IWS/VS system, a Separate 
PSB is reguired fcr each crline program- Each PSE consists of one or 
more program communication blocks (PCBs) , one for each data base the 
program uses. 

The PSE is generated, as shewn in Figure 2-30, in a similar manner to 
the EEI using the OS/VS assembler and linkage editor. The generated 
lead mcdule is stored in IKSVS. PSEIIB. 



INPUT 
DECK 



IMSVS. MACLIB 



MACROS 



L 



C 



L 



IMSVS. PSBLIB 





PSBGEN 



c> 



PSB 



PSB _ 



Figure 2-30- Prcgram Specification Block Generation (PSBGEN) 

Figure 2-31 shows the sequence of the macro statements in the ESEGEN 
input deck. 



( END 



PSBGEN 



REQUIRED: 1 
REQUIRED: 1 



( SENSEG 



PCB 



REQUIRED: ONE FOR 
EACH DATA BASE (DBD 
THIS PROGRAM USES. 

( SENSEG 




{ SENSEG 



PCB 



REQUIRED: ONE FOR EACH 
_J SEGMENT IN THE DATA 

BASE THIS PROGRAM ACCESSES. 



Figure 2-31- PSE-GEN Input leek Structure 
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The PSBGEN is executed by invoking a JCL cataloged procedure named 
PSBGEN, which is available in the IMSVS. EBOCLIE. 

The coding conventions fcr the FSB are exactly the same as fcr the DBD 



BASIC ESB CODING 

Following are the fcasic PSB control statement formats. 



ICE Statement 

This statement is coded once for each data base the program intends to 
use. The fornat is: 



/* 



|PCE |iyPE=DB 

| | ,EEEHAKI=dbdname 

I 

1 f « ) CM 

UPSOCOPT = <[G]Cl]CE]{D] } [P] 

I I L J [S] 

I 

I ,KEYIEli=value 



Le^ en d : 

TYPE=CE 

is a required keyword parameter for all data base PCBs. 

DBDNAME= 

specifies the name cf the DBD which is accessed via this PCB. It 
can be a physical or logical DBD, 

FPCCCFT= 

specifies the processing cctions on sensitive segments declared in 
this PCB that may be used in an associated application Frcgram. 
Specifying superfluous processing options is undesirable from a data 
base security point of view and can result in unnecessary additional 
data base processing. This operand allows a maximum of four 
characters. The letters in the operand have the following meanings: 

G - Get function. 
I - Insert function. 
E - Beplace function. 
D - Delete function- 
Note: The furctions above can be coded in any combination of 
three; if all fcur are required, code "A". 

A - Ail, includes the above four functions. 

E - required if command code D {path call) is to be used en get 
type calls or insert calls. Determines maximum length of the 
I/C area. P cannot be coded with L. 
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I - Load function f cr data base leading (except HIDAM) - 

LS- Segments loaded in ascending seguence only (HIDAW, BEAM}., 
This load option is required for HIDAM. 

KEYLEN= value 

is the value specified in bytes of the longest concatenated key for 
a hierarchical path of sensitive segments used by the application 
Frcgram in the hierarchical data structure. 

GSAM FCE: The format fcr tfce GSAM data base PCE statement is: 



/ 



/ - i 



PCE |TYPE=GSAK 

| ,EBDKASE=name,IBOCCPT=jG[S] 

I 
i -. • 1 



where: 

TYPE=GSAM 

is a required keyword parameter for all GSAM data base PCBs. 

DBDNAME^name 

is a required keyword parameter for the name that specifies the GSAM 
EEC to be used as the primary source of data set description. 
SENSEG statements must not follow this PCB statement. 

PB0C0P1= 

is a required parameter fcr the processing options on the data set 
declared in this ECE that can be used in an associated application 
program The operand is specified using the characters defined 
below: 

G - Get function 

L - Load function 

S - Large scale sequential activity. If specified, GSAM will use 

multiple-buffering. This is recommended for heavy sequential 

processing. 

Nfite: The GSAM ECE statements must follow the PCB statements with 
TYPE^TP or DB if any exist in the PSB generation. The convention is: 

IF FCBs - first 
DE PCEs - second 
GSAM PCBs - last 

SEKSEG_ Statement 

This statement is coded once for each segment the program is sensitive 
to in the EEE defined in the preceding PCB. The SENSEG statements 
should appear in the same hierarchical sequence as in the DBD. However 
only those segments shculd te included to which the program needs 
access. All segments should be specified in the hierarchical path to 
any required segment. Nc SENSEG statements should be coded for a GSAM 
PCB. Ihe basic format of the SENSEG statement is: 
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/ 



1 

SENSEG | NAKE=segname1 

I 

| ,FAFEKT-segname2 

I 



! f I 1 [P] 

![ ,PROCOPT = {[G ][ I ][ P ][D ]} [ P ] ] 



Legend: 

NAHE=segname1 

is the name of the segment type as defined through a SEGM statement 
during DBC generation. The field is from 1 to 8 alphameric 
characters. 

PAFENT=segname2 

is the name of the segment type that is the parent of the segment 
type whose name is specified in the SAME operand. If this SENSEG 
statement defines a root segment type, this operand must equal zero. 
For all dependent segment types, this operand must specify the name 
of the dependent *s parent. 

FBOCCFT= 

specifies the processing options allowable on this sensitive segment 
by an associated application program. This operand has the same 
meaning as the PROCOPT operand on the PCB statement. If this 
EROCCFT operand is not specified, the PCB FBOCOFT operand is used as 
default. If there is a difference in the processing options 
specified on the PCB and SENSEG statements, SENSEG FECCCFT overrides 
the FCB E5CCCFT. When loading a data base, you should specify a 
PEOCOPT only in the PCB statement. 

PSBGEN_Statement 

This statement specifies the end of the PSE and provides interface 
parameters for the application program. It is the last statement before 
the ENE statement. The basic format is: 



/' 



! 

! (COBOL) 
FSEGEN !LAKG-<FI/I > 

I (assehJ 

| ,CKFAT=YES 
|,P£BNAME=psbname 
J ,ICEFC£N= (451,WTCB) 



LANG= 



specifies the language in which the application program is written. 
It must be either CCECI, FL/I, or ASSEM, with no trailing blanks. 



CMFAI=YES 



should be selected, except for initial load programs. It provides 
an extra dummy PCB in the PSB. This benefits migration to online 
processing at negligible cost. 
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PSENAME=pstname 

is the parameter keyword for the alphameric name of this PSE. The 
name value fcr the PSIJARI must be eight characters or less in 
length. This nam* beccires the lead module name for the FSE in the 
library IKSVS.FSBLIB- This name must be the same as the program 
load module nane ir the program library- No special characters may 
be used in the name. It must be the name in the MBR= operand cf 
PSEGIN. 

I0EB0FN=(U51,KTCE) 

Should be coded as shown to concur with the recovery procedures of 
our subset- Whenever a read cr write data base I/C error would 
occur during batch processing, the CS/VS system console operator 
will be notified Inessage DFSC45U) . 

The reply should be 'ABEND'; DL/I will then abend with a UU51 abend 
cede- Ihe data set in error should then te recovered- See Chapter 
6, "Data Base Recovery," fcr details- This parameter can be omitted 
when initially loading the data base. 

Note; Before above reply is given, the operator should take proper 
actions to prevent the execution of any ether DL/I jobs against the 
affected data bases. See Chapter 6, "Data Base Fecovery," for 
details. 

END Statement 

__ _ ^_— _ _ _ _ __ _ 

This statement is required at the end of the PSB deck- It indicates the 
end of the input for the OS/VS assembler. 

/ - i 

/ I I I 

! IEND I | 

II! I 

i-.. .. j 



Sajfl§_Basic_PSBs 




cont--...^ ~_ -- — 3 - 

//SAMP102 (PL/I) in IMSVS.PEIMEJOB . 
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PROGRAM SPECIFICATION FOR LOADING 
THE PHASE 1 PARTS DATABASE 
PCB TYPE=DB,PROCOPT=L. 

DB0NAME=BE1PARTS,KEYLEN=20 

SENSEG NAME=SE1PART 

SENSEG NAME=SE1PST0K,PARENT=SE1PART 
SENSEG NAME=SE1PPUR,PARENT=SE1PAPT 
SENSEG NANE=SE1PGDSC,PAPENT=SE1PART 
PSBGEN IANG= ASSEM , PSBNAME = PE 1 PARTS 
END 



* PROGRAM SPECIFICATION FOR 

* PURCHASE-ORDER UPOATING OF 

* THE PHASE 1 PARTS DATABASE 
PCB TYPE=OB,PROCOPT=AP, 

DBDNAM5=BE1PARTS,KEYI_EN=20 
* 

SENSEG NAME=3E1PART>PR0C0PT=GP 
SENSEG NAME=SE1PPUR,PR0C0PT=AP,PARENT=SE1PART 
w 

PCB TYPE=GSAM,PROCOPT=G, 

DB0NAME=B00INP01 
PCB TYPE=GSAM,PPOCOPT=L, 
DB0NAME=B00OUT01 
PSBGEN LANG=COBOL.CMPAT=YES, PSBNAME =PElCPPUR,IOEROPN=( 451, WTOR) 
END 

Figure 2-32. Sample PSBs for Phase 1 

EXECUTION Or PSBGEN — JCL 

PSEGEN is run as a noriral Operating System job after IMS/VS system 
definition. IMS/VS system definition causes the procedure named PSBGEN 
to be placed in the IMSVS.PROC1IB procedure library. The following JCL 
cards are used to invoke the PSBGEN procedure. 

//PSEG2N JOE MSGLEVEL=1 
// EXEC FSEGEK,MEB= 

//C.SYSIN DD * 

FCE 

SENSEG The ccntrcl cards 

ESBGEK for FSE generation. 

END 



where keyword operand KEF= 

is the name of the PSB tc be generated. This name must fce the same 
as the name specified en the PSBNAME= operand of the FSEGEN 
statement. 



CODING PSEs FOR LOGICAL DATA BASES 



When a physical DBD contains logical relationships, the PCB and the 
applicaticn program can still refer tc the physical DBD. However, this 
shculd be restricted tc initial data base load programs. Eemember also, 
the logical child always contains the logical parent's concatenated key. 
This should net be fcrgctten when inserting a logical child in a 
physical DBD. You can never access a virtual logical child in a 
physical data base, since it dees not exist. 
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To use a logical data base, the program needs a separate PCB. This PCE 
is coded in the same manner as a PCB for a physical DBD. The cnly 
difference is that it refers to the DBD name and SEGMENT names of a 
logical DBD. You should only code SENSEG statements for the segments 
the program actually needs and the segments in the hierarchical path to 
those segments. All of this is based on the logical DBD, so the 
hierarchical path may well include physical and logical paths- Figure 
2-33 shows the PSB for the Phase 2 processing program PE2C0PDR, 
containing a PCB for both the logical data bases in addition to a PCB 
for the SHISAM data base. This PSB is listed in IMS VS. PRIMES RC, its 
PSBGEN can be performed with job //SAMP201 (COBOL) or //SAMP202 (PL/I) 
in IMSVS.PRIMEJOB. 

« PROGRAM SPECIFICATION BLOCK FOR PHASE 2 

« ORDER UPDATE PROGRAM PE2C0RDR. 

m CUSTOMER DATABASE VIEW 

* 

PCB TYPE=DB,DBDNAME=BE2PCUST,PR0C0PT=G,KEYLEN=6 
SENSEG NAME=SE2PCUST 

* ORDER DATABASE VIEW 
* 

PCB TYPE=DB,DBDNAME=BE2L0RDR>KEYLEN=14 
SENSEG NAME=SE20RDER,FR0C0PT=AP* 
SENSEG NAME=SE20PART,PARENT=SE20FDER,PR0C0PT=A 
SENSEG NAME=SE20SHIP,PARENT=SE20RDER,PR0C0PT=GI 
* 

* PARTS DATABASE VIEW 
* 

PCB TYFE=DB,DBDNAME=BE2LPART,KEYLEN=20 
SENSEG NAME=SE1PART,PPCC0PT=GRP 

SENSEG NAME=SE1PSTOK,FAPENT=SE1PART,PROCOPT=GR 
* 

PSBGEN LANG=C0BOL,CMPAT=YES,PSBNAME=PE2CORDR,IOEROPN=(<+51,WT0R) 

END 

Figure 2-33. Sample PSB for Phase 2 

CODING PSBs FOE SECCNDAFY INDEXES 

To use a secondary index, an application program should use a PCB with 
the following additional parameter in the PCE statement. 

The PCB Statement 

/ -i 

/ ! I I 

| |PCB |TYPE=DB,... ,PROCSEQ=inuxdbname 1 

III I 

t-- ...... --.- -_-„.----- . . . j 

PRCCSEQ=indxdfcnam€ 

specifies the name of the secondary index used to process the data 
base named in the DBDNAMS operand through a secondary processing 
sequence. The operand is invalid if PROCOPT=L or LS. 

Notes : 

1. The DBD specified in the PCB for the secondary processing sequence 
can be a logical DEC. No provisions are necessary in the logical 
DBD, but its root segment must be the target segment of the physical 
DBD. 
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2- If non-unjgue index fields are used, you must specify of the /SX 
field in cur subset. As a consequence, the sequence of root 
segments with the same index field value, when sequentially 
retrieved via the secondary index, will be unpredictable, "Phis 
sequence will also vary across reorganization of the target data 
base. 

Figure 2-3U shows the PSB fcx the Phase 3 processing program, EE3CEFDE. 
This FSB contains a ECE for the normal processing sequences and a PCE 
for the secondary processing sequence. 

* PROGPAM SPECIFICATION FOR 

# PUPCHASE-ORDER UPDATING OF 

* THE PHASE 3 PARTS DATABASE 
* 

# PRIMARY INDEX VIEW OF DATABASES 

PCB TYPE=D8,PP0C0PT=AP, * 

DBDNAME=BE3PARTS,KEYLEN=20 
* 

SENSEG NAME=SE1PART,PR0C0PT=GP 
SENSEG NAME=SE1PPUR.FR0C0PT=AP,PARENT=SE1PART 
* 
« SECONDARY INDEX VIEW OF DATABASES 

PCB TYPE=DB,FR0C0PT=GP,DBDNAME=BE3PARTS,KEYLEN=16, * 

PR0CSEq=BE3PSIDl 
* 

SENSEG NAHE=SE1PART 
SENSEG NAME=SE1PPUR,PARENT=SE1PART 
# 

PCB TYPE=GSAM,PROCOPT=G, * 

DBDNAME=BOOINP01 
PCB TYPE=G5AM,FFCCQPT=L, * 

DBDNAME=B00CUT0I 
PSBGEN LANG=C0B0l,CMPAT=YES,PSBNAME=PE3CPPUR.I0ER0PN=(451,WT0R) 
END 

Figure 2-34. Sample Phase 2 PSB 
THE DATA EASE LESIGN PBOCZSS 



The process of data base design in its simplest form can be described 
as: The structuring of the data elements for the various applications 
in such an order that: 

• Each data element is readily available by the various applications, 
new and in the foreseeable future. 

• The data elements are efficiently stored on secondary storage. 

• Controlled access is enforced for those data elements with specific 
security requirements. 

In practice, one is often fcrced to compromise, based on available 
resources in iranpewer, hardware and software. 



CCNCEP1S OF EA1A BASE DESIGK 

Eecause data base design is an area where there has been little formal 
standardization, there has been no consistent vocabulary for describing 
the concepts involved. This section presents the concepts and terms 
used in the following introductory data base design discussion. 
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Entities 

A data base contains informaticn about entities, 
that: 



An entity is something 



• Can te uniquely identified- 

• We may now or in the future collect substantial information about. 

In practice this definition is limited to the context of the 
applications under consideration. Examples of entities are: parts, 
projects, orders, customers, trucks, etc. It should be clear that 
defining entities is a major step in the data base design process. The 
information we store in data bases about entities is described fcy data 
elements. 

A illi§ SiSIiJDi i £ a unit of information that specifies a fact atcut an 
entity. For example, suppose the entity is a part. Name=Washer , 
Color=Green, and Keight=143 are three facts about that part- Thus these 
are three data elements. A data element has a name and a value. A data 
element name tells the kind of fact being recorded; the value is the 
fact itself. In the atove example. Name, Cclcr, and Weight are' data 
element names; Washer, Green and 143 are values. A value must be 
asscciated «ith a name to have a meaning. 

An occurrence is the value cf a data element for a particular entity. 
figure 2>-35 illustrates the concepts of data elements and their 
occurrences in recording the facts about two entities, parts (Entity A) 
and orders (Entity E). 



ENTITY A: 



PARIS 



DAIA ELEMENT 



CCCUFEENCES 



Name 



Value 



Value 



Part Number 

Name 

Unit Price 

Unit Quantity 

Stock Quantity 



0200371C 

Screw 

S3.CC 

100 pieces 

2CC0 



03003720 

Washer 

SI. 00 

100 pieces 

3000 



ENTITY E, 



OKCERS 



DAIA ELEHEST 



OCCURENCES 
Value ! Value 



Name 



Order Number 
Fart Name 
Fart Number 
Quantity 
Supplier Name 
Order Code 



190E6C 
Screw 
C3CC371C 
500 units 
Allied Screw 
A 



| 190E60 

! Bolt 

| 03003730 

I 300 units 

| Allied Screw 

I X 



figure 2-35. Concepts of Data Elements 
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Thj=_Tr.an§aj£tion 

Data in itself is net the ultimate goal cf a data base management 
system. It is the application function performed on the data which is 
important. The best way to represent that function is the transaction, 
which is the smallest application unit representing a user interacting 
with the data base. For example, one single order, one part inventory 
status. 
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Figure 2-36. The Transaction 
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In this chapter we will utilize the transaction for the data base 
design.. A similar role is set aside for the transaction in program 
design by adding detailed input, processing and output descriptions to 
the data element usage. 

£ccess_Paths 

Each transaction bears in its input some kind of identification with 
respect to the entities used (for example, the part number when 
accessing a Parts data base). These are referred to as the access faths 
of that transaction. In general, transactions require random access, 
although for perfemance reasons sequential access is sometimes used. 
This is particularly true if the transactions are batched and they are 
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numerous, relative to the data base size, or if information is needed 
from most data base records. 

For efficient random access, each access path should utilize the 
entity's key. Kith proper data base design, DL/I generally provides 
fast physical access via a key. Therefore, identification of the 
transaction access path is essential for a design to yield good 
performance. 

2k£_l5§JQS§ction/Eata_|lement_j5atrix 

A convenient waj to specify the transactions, the data element and their 
interaction is th€ transaction/data element matrix. Figure 2-37. 




< 

Q. 



is 

o 



PART NUMBER 
STOCK LOCATION 



UJ CUSTOMER NAME 

O CUSTOMER NUMBER 

CO 

3 ORDER NUMBER 



PART NUMBER 
CUSTOMER NUMBER 
PART QUANTITY 
ORDER NUMBER 



CD E 



Figure 2-37. 



Legend: [^DIRECT ACCESS PATH (KEY) 

O SEQUENTIAL ACCESS PATH 

The Transaction/Data Element Matrix 



The transaction/data element matrix specifies, in its simplest form, the 
processing intent of the application transactions against the data base 
elements: 



Petrieve; read only R 
Update in place U 

Add, insert I 

Delete D 

All cf above A 

Null, not sensitive - or blank 
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Th€ data elements which are direct access paths for a transaction are 
denoted by a boxed satrix item. These should be keys. Sequential 
access is indicated by a circle around the matrix item. 

2HI-5A1A_EAS1_CESIGK_TAS!S 

The process of designing a data base (Figure 2-39) can be generally 
divided into the following tasks: 

« Gathering reguiremects 

• Designing application data structures 

• Designing physical data structures 

• Design evaluation 



-DESIGN PHASE- 



GATHERING 
REQUIRE- 
MENTS 



DATA ELEMENTS 



DESIGNING 
APPLICATION 

DATA 
STRUCTURES 




DESIGNING 

PHYSICAL 

STRUCTURES 




jC 



DBDs 



DESIGN 
EVALUATION 



PHYSICAL 
IMPLEMENTA- 
TION 



DBDLIB 




DATA 
BASE 



OPERATION & 
EVALUATION 
MONITORING 



figure 2-38. Ihe Steps in Data Base Design 



Usually the above steps are repeated until the design satisfies the 
requirements. After this design process, the actual development, 
implementation Jdata base lead) and production begins. During 
production, the system is subject to monitoring which can give feedback 
for the design phase. This will be discussed in Chapter 9, 
"Cptimization". 
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GATHERING SECUIEEKENTS 

The first step of the data base design poses many questions: What do 
the applications need? What inputs are required to drive them? What 
data outputs will they produce? Sow are the data elements related to 
one another? Which elements are identifiers and which elements do they 
identify? Hew frequently are they used? Have input sources been 
specified for all data elements? 

Durinq the process of gathering requirements, these and related 
questions are answered primarily during conversations tetween a data 
base designer and an analyst frcm the department that requests an 
application. In some organizations, a set of fortes appropriately filled 
in marks the end of the requirements gathering step; in other 
organizations, less formality is involved- In any case, this first step 
in data base design ends when the designer collects the data needs of 
the individual applications that will us? the data base being designed. 

The requirements for a data base should contain: 

• The data being managed, that is, the entities and associated data 
elements 

• The relations between the entities and data elements as needed fcy 
the various users 

•• The functions being performed against the data, that is, the 
transactions 

• The access path as required by the transactions 

The first step in gathering the requirements is tc determine the 
entities- This is not a trivial task, because the choice of entities is 
dependent on the environment . 

A data element which, initially, is considered an attribute, could 
become an entity itself when new applications are added. For instance, 
the data. element eoler is normally seen as an attribute. But in a paint 
factory process it miqht very well be an entity itself. It should be 
clear that the chanqe of a given data element from attribute to entity 
could have a significant impact on the data structure- To avoid this as 
much as possible, one should be very careful in the choice of entities. 

To register the functions performed against the data elements, first 
construct the transaction/data element matrix- Optionally when the 
matrix becomes tec large, cne can construct a separate matrix for each 
major application. Another useful approach is to make a large drawing 
for display en the wall. This process is most effective if the matrix 
not only contains the application?; of the immediate future, but also as 
much as possible about future applications and data elements. 

Additional columns could be added for miscellaneous information such as: 

Occurrence frequencies cf transactions and data elements 

Size and format of data elements 

Priorities and response/turnaround time criteria 

Availability (how long can the function be suspended) 

Security (who may have access to the information made available by 
this transaction) 
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• In-put/output descriptions per transaction, for application program 
design 

The transaction/data element matrix, together with a detailed 
description of the data fcase and its use, constitutes the requirements 
for the design step- For the detailed description of the data base, its 
segments and fields, a documentation scheme should be established. As a 
minimum, forms should be used for a manual registration of the data 
base, the segment layout, the fields and their attributes. It is very 
important to register which program uses which data elements. The next 
step would be to use the Assembler DSECT, COBOL COPY, or PL/I XINCLODE 
facility for centralized management of segment descriptions. 
Ultimately, a data dictionary system might be utilized. 

For each phase cf cur saiple environment, we can now construct a 
transaction/data element matrix. 

The phase 1 transacticr/data element matrix is shown in Figure 2-39. It 
is clear the main entity is parts. Other possible entities cculd be 
purchase order, supplier and stock location. However, we assume no need 
to gather mere informaticr en these in our Phase 1 sample environment. 

Notice, the following information is added to the transaction data 
element matrix: 

• For each data element, we list its size and its occurrence per 
entity. C - 4 means that this data element occurs a minimum of zero 
times, and a maximum of four- 

• For each transaction, we list its average frequency in weeks (K) or 
days (C) . 

£^ase_2_Transactign^Data_Slement_Ma trix 

In the phase 2 environment, we add the Customer Order Processing 
application. This extends the phase 1 transaction/data element matrix of 
Figure 2-39 to the one shown in Figure 2-40. Essential here is that, 
besides adding new data elements for the customer order processing, this 
n£ « application also requires the existing PARTS data elements. 

Also notice that the part number data element appears beneath both the 
PARTS and the CUSTOMER ORDERS entities. This constitutes the basic 
requirement fcr a linkage or relation between these entities as «e «ill 
see later. 

Fhase_3_Transaction/Bata_Eiem€jQt_Mirix 

In the phase 2 environment, we added the purchase order inquiry 
transaction, T23FClliC.- This transaction requires a direct and a 
sequential access path tc the purchase crder information based on the 
purchase order number. This is because we want to be able to list an 
individual purchase crder, cr a range of purchase orders in their order 
number sequence. See Figure 2-41. In practice, this access path cculd 
also be used fcr the purchase crder change ITE1FOCNG) and delete 
(TE1PCDEL) transactions. 
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Legend: | | DIRECT ACCESS PATH (KEY) 

O SEQUENTIAL ACCESS PATH 

Figure 2-39. Transaction/Tata Element Matrix for Phase 1 
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Figure 2-'40. Iransaction/Data Element Matrix for Phase 2 
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Figure 2-41. Transaction/Data Element Matrix tor Phase 3 
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DESIGN THE APPLICATION EATA STRUCTURE 

The data elements can now be arranged in an application data structure, 
which consists cf cne ci mere hierarchical data structures. We always 
construct hierarchical data structures based on the transaction/data 
element matrix; that is, the way the application program views it. 



S«2ment_G rouging 

For each transaction, we start with the access path of 
to the entity, and construct a desired hierarchical vie 
transaction. If more than one entity is accessed in one 
multiple hierarchical structures are required for that 
each hierarchical structure, we try to group the needed 
the same type of segments. Each root segment of such a 
contains the key field which is used in the access path 
key fields (fcr example, part number and stock number) 
access path, these may become the sequence fields of a 
combination. 



that transaction 

w for that 
transaction, 

transaction. For 
data elements in 
basic structure 

• If multiple 

are used in one 

parent/child 



The first field in the rcct segment is the key; the sequence field. To 
the root segment are added these data elements which are of a general 
nature, frequently used and/or compact, and occur once (or traximum, 
perhaps 3 times) per entity. 

Next we group those data elements together in segments which belong 
logically to each other, based on their nature and use. Likely 
candidates for separate segments are those data elements which have 
multiple occurrences for a given root- The final result of the logical 
structure desicn step is a set cf hierarchical data structures. These 
represent the view of the data by the different application programs, 
the application data structure. 

££§§§-.1 lEEiiS§*i2£-.P§i5-Structure 

Based en the transaction/data element matrix of Figure 2-39 and above 
guidelines for designing application data structures, we construct the 
following structure for the phase 1 Parts data base (Figure 2-42). 



PART 
(SE1PART) 



STOCK 
(SE1PSTOK) 



PURCHASE 

ORDER 
(SE1PPUR) 



Figure 2-42. Phase 1 Application Data Structure 



Access_Paths 

Sequential access is needed via the part short name, FE1PGSNK and direct 
access is needed via the part number FE1PGPNR. We can, however, process 
the TE1INVRP transaction in part number sequence and then sort the 
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output in part short name sequence if needed. Direct access via part 
number is very important for later online processing, 

2£e Root Segment, SFlFABT 

The rcctkey is the part number FE1FGFNF field. The next step is to add 
the following fields to the rcct segment because they are of general use 
and occur for each part only once: 



Name 

FE1FGPNF. 
FElPGSNM 
FE1FGNEK 
FE1FGOLE 
FE1PGEQV 
FElPGlNl 
FElPGPFI 
FE1PGDIM 
FE1FGLNK 



Description 

Part Number Code 

Part Description - Short Name 

Net (Superseding) Part No. 

Old (Superseded) Part No. 

Equivalent part No. 

Onit of Keasure 

Price 

Dimensions 

Part Name (long Description) 

SEGMENT LENGTH 



LengtJ: 

8 
13 

8 

e 

8 
8 
8 
8 
50 
lli 



He define separate segments for stock and purchase order data elements 
because each can have multiple occurrences for each part and they are 
used separately. 



The_Stock_S€3ment,_SEjPST0K 

This segment has 1-6 occurrences for each part: 



Name 

FElPSLQC 
FE1PSDA1 
FE1PSCNT 
FE1PSISS 
FE1ESEEC 



Description Igngth 

Stock Physical location Code 12 

Stock Physical Count Date (MMDDYY) 6 

Stock Physical Count Quantity (TALLY) 6 

Stock Ictal Issues Current Period 6 

Stock Total Beceipts Current Period 6 

SEGMENT LENGTH 36 



Tkf-fy^hase^Order^Segffent^SEJFFUE 



Name 

FE1EPCNE 
FE1PPOET 
FE1FFCSD 
F21PPQOI 
FE1PPQRD 
FE1FPDD1 



Description LiUSth 

Purchase Crder Number 6 

Purchase Order Date WBDDYY 6 

Supplier's Kame 20 

Quantity Ordered 6 

Quantity Eeceived 6 

Delivery Date MMDDYY 6 

SEGMENT LENGTH 52 



The above application data structure of the Phase 1 Parts data base. 
Mill be input for the physical data base design in the next design step. 

jghase_2_AJ2J2licaticn_Data_Structure 

To support the Phase 2 transaction/data element matrix of Figure 2-40, 
we need two hierarchical structures in addition to the one shown in 
Figure 2-42. The result is shewn in Figure 2-43*. The design of the 
segments in the new hierarchical structures is done similar to the 
design of the Phase 1 Parts data structure. 
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CUSTOMER 
ORDER 



DETAIL 



CUSTOMER 



SHIPMENT 



CUSTOMER 
ADDRESS 



STOCK 



PART 



STOCK 



"py <£ 



PURCHASE 
ORDER 



CUSTOMER 
ORDER 



Figure 2-43. Phase 2 Application Data Structure 



The following considerations apply: 

• The hierarchical data structure PARIS is extended with a CUSTCMEB 
CEDEP segment. This provides the customer order per part relation. 

« Several segments appear in different structures. They also vary in 
their data element content. This is essentially data redundancy, 
which will be addressed in the physical design step. At this time, 
hpwever, we are mainly interested in the data structure as needed by 
the transactions. 

Note: In your situation, toes* structures could be far more complex. 
For instance, the Custcner data structure could have separate segments 
for accounts receivable, marketing statistics, etc. The PAFTS structure 
could have a component and assembly structure. This is not addressed in 
our sample but can te easily implemented with DL/I. 

£b.§§S_J AE£iicaticjn_Data_Structure 

The essential additional requirement of Phase 3 (see its transaction/ 
data element matrix en Figure 2-41) is the need for access to the part 
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and purchase order data elements via the purchase order number. This is 
reflected in the Fhase 3 application data structure in figure 2-44. 



CUSTOMER 
ORDER 



DETAIL 



CUSTOMER 



SHIPMENT 



CUSTOMER 
ADDRESS 



STOCK 







PART 
































s 




S 

/ 




S 


' 




f 


s 


STOCK 




PURCHASE 
ORDER 


s 


CUSTOMER 
ORDER 


S 



PURCHASE 
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PART 



Figure 2-44. Phase 3 Application Data Structure 



DESIGN THE PHYSIC*! DATA STBUCTUFES 

In this step, the logical structures are matched against the functions 
and characteristics of DL/I. Physical data base structures are defined 
and specified in EEDGEK control statements- The CL/I storage 
organization and OS/VS access method are selected. Additional 
considerations may yield changes in the segment design. See 
Figure 2-45. 
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GBCOF IN CBE SEGMENT < 



•> SEEABATE SEGMENTS 



Few occurrences (<3) 

Small (<20 fcytes) 

High use (every access 
tc record) 
Bead-only 

General use 

Only dependent upon a 
single data element 



Multiple occurrences (>10) 

Large (>100 bytes) 

Low use (once a month) 

Update, Insert, Eelete 

Secured use 

Dependent upon relation 
of data elements 



Figure 2-45. Grouping Data Elements intc Physical Segments 

The numfcers shewn in Figure 2-45 are not fixed. They merely provide a 
basis fcr your own estimates- Additional considerations: 

• Single versus multiple occurrences. If a data element has a high 
number of occurrences, it is likely tc be a segment itself, 
especially if it is large- If it is small and highly used, then all 
its occurrences could be stored in the same segment. However, the 
occurrence control would then be the responsibility of the 
application program, as DL/I itself dees net provide for multiple 
cccurrences of the name field in a segment. 

• A very large segment can have a negative impact on DL/I*s management 
of space on direct access devices. So the basic rule is: "Try to 
keep them more or less the same size". 

• If a data element needs special security (that is, only particular 
applications say have access to it) , it can be stored in a separate 
segment together with other data elements with the same security 
requirements. 

The final result of the physical structure design steps is the data base 
descriptions (DEDs) and program specification blocks (PSBs) for the data 
bases and their processing programs. 

f^§§f-i-ElJI§i£§i-P5l3-I§5S-.2Ssian 

He will now match our requirements as specified in the applicaticn data 
structure of Figure 2-42 and the transaction/data element matrix of 
Figure 2-39 with the available EL/I functions as presented earlier in 
this chapter. The outcome of this matching is the physical data base 
design reflected in the EEC and the physical data set attributes. 

i®i§£iiS3 2iia Base Organization 

Access methods can, in general, be changed during reorganization without 
affecting applicaticn programs. Still, because the access method is one 
of the most critical performance factors, it should be carefully 
selected. First we will discuss selection of the DL/I access method, 
HDAM, HIDAM, or SHISAH. 
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£k£2_tc_Chogse_HEAM: hdak is recognized in practice to be the most 
efficient storage organization of EL/I. It should be your first choice, 
at least in the online environment. HDAM's prime advantages are: 

1. Fast direct access (no index accesses) with few I/O operations 

2. Single data set and associated control blocks 

3. Small working set in main storage for EL/I 
U. Good physical seguential access 
Disadvantages of HEAM are: 

1. You need a randomizing module. 

2- Seguential access in root key order is not possible if the physical 

seguence of data base records in storage is not the same as the root 

key seguence. This is dependent on the randomizing module and root 
key characteristics. 

In many cases, the disadvantages for HDAM dc not apply or can be 
circumvented. The effort needed to circumvent should be weighed against 
the savings in terms of main storage and CPU usage. There is no doubt, 
however, that an application with cnly HDAM data bases is the most 
compact one. Seme possible solutions for the above HDAM disadvantages 
are: 

1. The IMS/VS system provides a general randomizing module, EFSHBC40, 
which can be used for any key range. Furthermore, the section "HDAM 
Eandomizing Modules" in Chapter 7, "Installing IMS/VS," will provide 
you «ith guidelines on how to write your own randomizing module. 

2. If heavy seguential processing is reguired and a randomizing module 
which maintains key seguence cannot be designed, then sort 
technigues can be used: 

a. Tf the program is non-input driven, as is the case with many 
report programs, simple Get Next processing presents all the 
data base records in physical sequential order. The output 
could then be sorted in the desired order. Also, in many 
instances, only certain selected segments are required. So the 
output file of the extract can be a fairly small file. 

b. If there are input transactions which would normally be sorted 
in root key sequence they should instead be sorted in physical 
sequence. This can be readily dene with an E6 1 sort exit 
routine which passes each root key to the randomizing module 
for address calculation and then sorts on the generated 
addresses plus root key instead of the root key itself. An 
example of such a routine, DFS0ASB1 is provided in 
IMSvS.FEIMESBC. 

3. A secondary index could be built with the root key as index search 
argument. The cost of this should be weighed against the cost of 
sorting as in 2 above. The secondary index provides full gereric 
key search capability, hewever. 

He will select HEAM as the DL/I access method for our initial Farts data 
base, and will use Technique E above in loading it. (Fcr details see 
"Loading a HEAM Eata Base" in Chapter 5.) 

wh£n_to_Choose_HIEAM: If ycu cannct use HDAM for seme reason, then use 
HIdIh (see above discussion). 
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Hl!§IJ_tc_Chcose_SHISAM: This access method should only be used as a 
migration tool. That is, if your organization currently has files based 
on ISAM or KSES access methods. It is not recommended for new data 
bases. With SHISAM, new programs can use the Dl/I interface with full 
recovery function. Existing VSAM programs can access the data base as a 
regular KSDS and elder ISAM-based programs can use the ISAM-VSAM 
interface. 

Ke will utilize a SEISAK data base in cur phase 2 environment. 

Which_CS^VS_Accass_Jethod 

For HDAM you could choose either ESDS or OSAM as the physical access 
method. There is net much difference as far as BL/I is concerned, 
although CSAM requires less main storage for code and control blccks. 
In general you should select ESDS if your installation already uses VSAM 
or plans to use it for other data bases. 

The real benefits from CSAfi are gained when you have an application 
which uses HDAM/OSAM exclusively. In any case, conversion from 
HDAM/CSAM to HDAM/VSAM is relatively simple once you have gained 
experience with VSAM itself. 

For the phase 1 data base we will select OSAM as the physical access 
method . 

Ilii§i:£§i_^§31§Si- Design 

In the final steps of segment design we must look at the physical 
parameters more closely: 

• The segment length 

• The number cf occurrences per segment per parent 
<• Location of segments in the hierarchy 

• Average data base record size 

£§5C2£S^SS®_^§EfSi§ : Tne main measure of access performance is the 
number of I/C requests necessary to satisfy the calls an application 
program issues. These are mainly dependent upon the physical data base 
design and the data base buffer pool size; the latter will be discussed 
in Chapter 9, "Optimization." Second, the number of required EL/I calls 
should be weighted. 

Basic recommendations (HDAM and HIDAM) : 

• Try to locate the segments most often used together with the root 
segment into one control interval/block. The segments are initially 
physically stored in hierarchical sequence so the most frequently 
used segments should be en the left of the structure (low segment 
codes) . 

• Try to avoid long twin chains, that is, many occurrences of a 
particular segment under one parent. Chain length should be 
estimated in terms of blocks needed to store such segments. For 
example, 100 segments cf 20 bytes (including prefix) cause less 
performance problems than K segments of 1500 bytes each if the 
block was 3000 bytes. See also the discussion of the "bytes" 
parameter under Basic F.eccmmenda tiens (HDAM) below. 
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• Inserts after initial lead will first check the block of the 
hierarchically preceding segment for available space- If nc space 
is found,' nearby blocks in the buffer peel are examined. If still 
nc space is found, a bit nag block is used to search for space 
within *3 cylinders in cur subset. The bit map block contains one 
bit for each block in the data set. Eit map blocks are repeated 
each N blocks; N is nuaber of bits in a block. The bit is set to 
one if the corresponding block contains enough consecutive free 
space to hold the largest segment (including prefix) of the DBE. If 
nc space is found, the segment is stored at the end of the data set 
for HIDA2J and in the overflow area for HDAM. 

Basic recommendation (HDAH): 

• During consecutive inserts (nc intervening calls) of segments of a 
particular data base record, the bytes parameter in the RMSAKE 
keyword in the DBD statement will limit the amount of data stored in 
the root addressable area. If the limit is reached (bytes includes 
prefix) consecutive inserts are placed in the overflow area. Using 
this parameter, especially during initial load and reload, can 
benefit an egual distribution in the case of a large variation in 
data base reccrd size. See also, HDAM space calculation later in 
this chapter. 

Physical Data Base Structure for phase 1 

Applying above guidelines to the phase 1 Parts data base gives the final 
physical data base structure cf Figure 2-46. 



HDAM, OS AM 



SET PART 10,000 



10,000 



80, 18, 98 



FE1PGPNR 



SE1PSTOK 40,000 



0, 6, 20 



40, 6, 46 



FE1PSLOC 



SE1PPUR 2000 


0, 


1,4 


60, 


6, 66 


FE1PPONR 



4^ 



SE1PGDSC 3000 



0, 0.3, 1 



80, 2, 82 



Figure 2-46. Physical Data Base Structure for Phase 1 
PAF1S Data Base 



As you will notice, we created a fourth segment, SE1PGBSC which contains 
the full tarts descriptive name, FE1PGLNM, since: 

• This information is rarely needed, especially in the foreseen online 
processing 

• By bringing back the root segment from 148 bytes to 98 bytes 

(including prefix) we improve the segment insert processing cf the 
stock and especially the purchase order segment. This results 
because the free space bit map is based on the largest physical 
segment size. 
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Furthermore, we added a dummy field to the segments. This could be done 
in practice if you expect the segment to be expanded in the near future. 
At least you should make all segments an even number of bytes. 

We also added to the data base structure in Figure 2-U6 the main 
physical segment attributes which are cf most importance for performance 
considerations. It is recommended that you maintain such structural 
figures for your data bases. They have proven to be very valuable for 
performance monitoring and design reviews. A description of those 
attributes follows in Fiqure 2- t n. 



SEGMENT NAME, OCCURRENCE 



FREQUENCIES (MIN, AVERAGE, MAX) 



LENGTH (DATA, PREFIX, TOTAL) 



SEQUENCE FIELD NAME 



rO 



Legend: 



• Segment name, occurrence specifies the segment name and the total 
number of this segment occurrence in the data base. 

• Frequencies specifies the minimum, average and maximum number of 
occurrences for this segment per parent occurrence. 

• Length specifies the segment data length, the segment prefix length 
and the total (=sum of data ♦ prefix) length of the segment. 

• Sequence field specifies the name of this segments sequence field, 
if any. 

Figure 2-47. Specification of Physical Segment Attributes 

Codina_the - Phase_ < 1_EABTS_EEE^HCAM 

We can now code the DBE and discuss the final parameters such as pointer 
options and Cl/blocksize parameters. Some iteration with the preceding 
section is normally necessary because the pointer options selected 
influence the size cf the segment prefix and, as such, can have an 
impact on physical segment design. The final DED of our Phase 1 Parts 
data base is listed in Figure 2*22 earlier in this chapter under the 
topic "Basic EEEGEN". 

££Usiderations_f or_Pginter_S.election 

Eecause there is no use expected of the physical child last pointer in 
any segment, code PARENT = ((segname, SNGL)) in all dependents. Because 
of this (no deletes after retrieve last), only physical twin forward 
pointers are needed. Code PTR=1 in all segments. Eecause there is 
never more than one occurrence of the SE1PGDSC segment for any part, the 
physical twin forward pcintei for this segment should be suppressed; 
code PTE=NT. 



2.82 IMS/VS Erimer 



Se lee tincj_C£/Block sizes 

In choosing the CI/blccksiz€ the following considerations apply: 

• Try to fit all highly needed segments of a data base record into one 

(or more consecutive) Cl/tlocks- 

• One tlocksize for all data base OSAM data sets (if any) will limit 
the amount of sucpcols. However, using a unique size for a highly 
used data base allows a dedicated subpool specification for that 
data base. 

• Large blccksizes favor sequential processing and DASD space 
utilization. Cn the other hand, if you are primarily processing 
directly, you should determine the segments needed per data base 
record per transaction. 

Easic recommendations fcr the practical minimum Cl/tlocksize for ESDS 
and OSAM data sets are given fcr each device type in Figure 2-48. The 
underlined numbers would be a general "best fit" for OS/VS1. the 
numbers between parenthesis would be the general "best fit" for 0S/VS2. 



Device Tyj:e 


| OSAM 


BlO 


cksize or. VSAM ESDS 
(blocks/track) 


CIsize 


2314/23 


IS 


1536 
(«) 




(2C48) 
(3) 




3330 


1536 




2C48 
(6)" 


(U096) 
(3) 


3340 


1536 
(5) 




2560 
(3) 


(4096) 
(2) 


3350 


(4096) 
4 



nnnn: OS/VS 1 Recommendation 
(nnnn) : 0S/VS2 Recommendation 
Blocksizes 1536 and 2560 are only applicable to OSAM 



Figure 2-46. Fcccmmended CI/Blocksize Parameters 



Additional considerations: 

• In case of large data rase records (greater than 500 bytes) and/or 
heavy sequential processing and/or large data bases, you should 
consider increasing the sizes shown in figure 2-48, especially fcr 
OS/VS 1. 

• For OSAM, the blocksize is limited to the maximum non-keyed 
tlocksize of a track. 

For KSDS, for INEEX data bases, you should select a control interval 
size of 2048 or U096 for the data component and 1024 for the index 
component. 
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AN£H # BEN, J.YTJ.S and SIZE Parameters for HD&M 

The following tasic guidelines apply tc above parameters for a HEAM data 
base: 

1- SIZE = 5 X AVBI 

2. EYTES = SIZE 

3. RBN = 1.25 X NROOTS X AVFL/SIZE 

4. AKCH = 1-25 J KBCCTS/5EN 

Where: 

• AVEL is the average data base record length, including segment 
prefixes. 

« SIZE~ is the net Cl/blocksize. Remember that DL/I will allocate some 
ccntrcl fields %ithin your selected Cl/block. These are: 

Free space anchor point: 4 bytes 

For each anchcr pcint: 4 bytes (only in the root addressable 
area) 

VSAH control fields (ESDS) : 7 bytes 

In addition, these will be a free space element of 8 bytes for each 
consecutive free space of 6 bytes cr more in the Cl/block. 

• BYTES is the maximum number of bytes of a single data base record, 
to be inserted by consecutive insert calls against the same PCB. 

• ANCH is the number cf rcct anchor pcints per Cl/block {round to next 
higher) • 

• RBN is the number of Cl/blocks in the root addressable area. 

Ideally, 4 to 5 data base records should fit in one Cl/block. However, 
for very large data base records -- one average record per N Cl/blocks 
— you should consider a randomizing algorithm, which skips every N 
Cl/blocks. The BYTES parameter should then be no less than the average 
data base record size and the number of anchor points per Cl/block 
should be one. 

l25JlJL§» Qur PARTS Data Base: 

For our PARTS data base, we calculate (assume 10,000 records): 

AVBL = 

( 10, 000X98+4 0,000X46+2, 000X66 + 3, 000X82)/ 10, 000 
= 320 bytes 

The maximum data base record length is: 
S8+20X46+4X66+82 * 1364 bytes. 

And the minimum data base record length is: 
98 bytes. 
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The data and prefix length of each segment can be found in the DBDGEN 
macro expansion output listing. The field "SEGMENT LENGTH" contains the 
data length of the segment in bytes. The field "LENGTH OF SEGMENT 
PREFIX" contains the length in bytes of the segment prefix. 

SIZE : 5 X 320 = 1600, rcunded to 2046 

EYTF.S « 2048 

Because our maximum data base record size is 1364 bytes, this could be 
specified as the BY3ES limit. 

BBN = 1.25 X 10, COO X 32C/2C46 = 1954 

For 3330, this would require 326 tracks or 18 cylinders. An initial 
space allocation of 20 cylinders (10% for the overflow area) will be 
appropriate. 

ANCH * 1.25 X 10, 000/1954 = 6 

He now check our net Cl/block size in the root addressable area, which 
is: 

2048 - 4 - 4 X 6 = 2C2C 

This is large enough to hold, generally, more than five data base 
records. 

5§IiSiS9-5Sft|_Data_Sets 

VSAM data spaces are defined with its Access Method Services. Job 
//SAMP270 in IMSVS.PRIMEJOB shows hew to do this for a HDAB (PAFTS) data 
base and a HIDAM (Customer Order) data base. Note that the DATA and 
INDEX components are separately named. 

Whenever defining a KSES, ycu should check the DBDGEN output listing. 
It gives the proper access method service control statements for the 
definition of the KSDS (that is, the location of the key in the KSDS 
record) • 

Note: Job //SAMP27C defines the VSAM data sets in the VSAM data space 
defined with job //SAMP007. 

OS J M _ £ a t a _ S e t .A^loc at 4 c. n 

OSAM space can be allocated via normal JCL as an OS/VS sequential data 
set. No DCB information should be provided in the JCL. OSAM space can 
be reused but only if the tlccksize (SIZE parameter in BBC) has not been 
changed, that is, the same as indicated in the DSCB on DASD. 

Job //SAMP170 in IKSYS-FBIKIJCE, which loads the Pliase 1 PABTS data base 
shows how to allocate the space fci the OSAM dataset. 

Fhas^J^Physical^Eaia^Base.Desijgn 

The Phase 2 application data structure in Figure 2-43 can be easily 
implemented with the use of the logical relationship function of DL/I. 
Merely define the crderline segment as a logical child of the part 
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segment as shewn in Figure 2-43- In addition the following 
considerations apply: 

•• The physical data base design for the Parts and Customer Crders data 
bases is dene in much the same vay as for Phase 1. 

• The access method fcr the CUSTOMER CBDEF data base is HIDAM/VSAM. 
This is done tc shew an example of a HIDAM data base. 

• The access method for the PARTS data base is changed to HDAM/VSAM to 
provide a V5AM enly environment. 

• As discussed previously, we will use a separate SHISAM data base for 
the customer name and address instead of duplicating that data in 
the Customer Order data base. The key (customer number) cf this 
SHISAM data base will be stored in the root segment of the Customer 
Order data base. 

Notes: 

1. The real logical child can, in reality, be located either in the 
Parts or the Customer Crders data base. Their is no difference for 
the application program as tc where it is located (except for the 
initial lead program). Which implementation to choose is purely a 
performance matter. This will be discussed in Chapter 9, 
"Optimization," under the topic "Optimizing Physical and Logical 
Twin Chains." 

2. Whenever the accounts receivable application is converted to DL/I, 
the SHISAK data base could be converted to a full HDAK or HIEAM data 
base. Additional segments can then be added with minimal impact on 
the existing DL/I application programs. Also, if necessary, a 
logical relationship could be implemented between this Customer data 
base and the Customer Orders data base, much in the same way as 
between the Parts and the Customer Orders data base. 

Two sets cf EEDs are needed for the phase 2 applications: 

• Physical EBEs with legical relationships, and 

• Logical EEEs for the application programs. 

The DBDGEN process of these DBDs is described under the topic "DEEGEN 
for Logical Data Bases" earlier in this chapter. The physical DBDs for 
the Parts and Customer Orders data bases are shewn in Figure 2-24. 

Due tc expected high activity against the logical child segment all 
associated pointers are specified forward and backward- This shculd be 
done in all cases where there is considerable activity expected with a 
logica} child. 

The corresponding legical Parts DBD (EE2LPART) is listed in Figure 2-25. 
The legical Customer Orders data base is listed in Figure 2-26. 

All above DBDs, together with the SHISAM DBD (BE2PC0ST) are also 
included in IMSVS. PEIMESFC. Their EEBGENs can be executed with job 
//SAHP210 in IMSVS.PRIMEJOB. 

i!iase_3 Physical £ata Ease Eegign 

In our Phase 3 sample data base design, we will use the secondary index 
function cf DL/I. 
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Analyzing our Phase 3 requirements as reflected in its transaction/ data 
element matrix (Figure 2-41) and application data structure (Figure 
2-U4) , we see the need for the access of the parts data via purchase 
order number. 

Actually, the best nay, from a pure data -base design point of view, is 
to implement this via a logical relationship. This logical relationship 
should then be established between a new Purchase Orders data base and 
the Parts data base- However, we choose to use the secondary index 
function for this with the following considerations: 

• Exemplify the difference between the logical relationship and 
secondary index functions. 

• Adding of the secondary index to the PAFTS data base has the least 
impact on the existing Phase 1 and Phase 2 application programs. 

• If there is no expected extension of the purchase order application, 
it might also, in a real live situation, be the most economical, 
solution. 

Furthermore, we will select the parts segment as the index target 
segment. This is according to the limitations of our subset as set 
before (that is, target=rcct segment) • In this way, the Phase 3 
reguirements can be very easily implemented, especially by the 
application programs. 

Above discussions are reflected in our Phase 3 DBDS: 

• The physical Farts data base EE3PAETS 

• The physical Customer Crders data base EE20RDEB and its primary 
index BE30EDEX 

• The secondary index DBD BE3PSID1 

These DBDs are all included in IMSVS.PBIMESBC. Their DBDGENs can be 
performed with jet //SAHF310 in 1MSVS. PFIHEJOB. The DBEs for BE3PAETS 
and EE3PSIE1 are shown in Figure 2-29 under the topic "DEDGEN For 
Secondary Indexes". 

Note: The Phase 3 application program PE3CFPUB uses a PSB which 

references the Phase 3 physical DEEs. Ideally, this PSB should use a 

Phase 3 logical PAETS data base BE3LPAET. This DBD is much the same as 

for Phase 2. It is suggested that you exercise this change yourself. 

DESIGN EVALUATION 

Following the physical data base design, & design evaluation should be 
performed. The two main questions for this evaluation are: 

• Does the data base design support the applications functional 
reguirements? 

• Does the data base design provide for a satisfactory performance? 

The first guestion is not considered here, because it is too application 
and installation dependent. The second question's answer is also 
largely installation dependent. Hcwever, Chapter 9, "Optimization, " 
provides you with a simple hand calculation technique to compare 
alternative designs. In addition, a checklist is included which 
addresses the most important performance factors for DL/I data bases. 
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CHAPTER 3. DATA COMMUNICATION DESIGN 



This chapter is complementary to the previous chapter on data base 
desigr. It provides the data communication designer and system analyst 
with a detailed description of the IMS/VS data communication functions, 
and guidelines or how to use these functions. 

The three main parts in this chapter are: 

• A description of a-n online application sample. The sample 
application is used to demonstrate the general requirements of an 
online systenu The sample application is used also in the examples 
in the remainder of the chapter. 

• A more formal description cf the IMS/VS data communication 
functions, including the specification of IMS/VS message format 
service usage. 

• An extension of the data base design process of the previous chapter 
into the data communicaticn area. Besides considerations for online 
data base design , this part provides guidelines for online 
application program design and message format design. 

The basic requirement of phase 4 of our sample environment is to run the 
phase 3 (see Chapter 2) sample applications in an online environment. 

PHASE 4 SAMPLE DA1A BASES 

The phase 4 sample data base requirements are in general the same as for 
phase 3. The only added requirement is that they should be accessible 
online. As we will see, this usually will not require any change in the 
data base design. In the sample online system we will use the phase 3 
data bases. 

PHASE 4 BATCH EECGEAMS 

In phase 4 of our sample system, both the Inventory Report Processing 
and the Purchase Order Processing will remain batch applications. We 
will show in the sample system how the pre-phase 4 programs of these 
applications can be executed with the online data bases without any 
modifications to the programs. 

PHASE 4 ONLINE PROGRAMS 

The essential requirement for phase 4 is to perform the Customer Order 
Processing as an online application, using IMS/VS data base/data 
communication facilities. All the transactions defined in phase 2 (see 
"Sample Application for Phase 2" in Chapter 2) should be available via 
the 3270 Information Display System. In addition a simple online 
customer name and address inquiry application will be implemented. 
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IWS^VS^DATA.COMMONICATICN^FACIIITIES 

In the, following sections, we will discuss the IMS/VS data communication 
facilities within our subset. It is assumed that you have a clear 
understanding of the concepts and terminology as presented in Chapters 1 
and 2. 

To explain the IMS/VS data communication facilities, we will follow a 
message through the system. 

THE MESSAGE 

The goal of IMS/VS is tc perform online transaction processing. This 
consists of: 

1. Receiving a request for work to be done. The reguest is entered at 
a remote terminal. It is usually made up of a transaction code 
which identifies to IMS/VS the kind of work to be done and some data 
which'is to be used in doing the work, 

2. Initiating and controlling a specific program which will use the 
data in the reguest tc dc the work the remote operator asked to be 
done, and to prepare some data for the remote operator in response 
to the reguest for work (for example, acknowledgment of work done, 
answer to a query, etc.). 

3« Transmission of the data prepared by the program back to the 
terminal originally requesting the work. 

The above sequence is the simplest form of a transaction. It involves 
two messages: an input message from the remote operator reguesting that 
work~be done, and an output message to the remote operator containing 
results or acknowledgement of the work done. 

5JSlti£le-and_ Single -Segment_ Messages 

A message, in the most general sense, is a sequence of transmitted 
symbols." In the context of IMS/VS, this is called a transmission. A 
transmission may have one or mere messages, and a message may have one 
or more segments. A segment is defined by an end-of-segment (ECS) 
symbol, a~message is defined by an end-of-message (ECM) symbol and a 
transmission is defined by an end-of-data (EOD) symbol. The valid 
combinations of the conditiens represented by ECS, ECM, and ECD are: 

Condition 5.§E£S§ifits 

EOS EOS 

ECM ECS/ECM 

EOE EOS/EOM/EOD 

The relations between transmission, message and segment is shewn in 
Figure 3-1. 
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Figure 3-1. Transmission, Message, and Segment Relations 

The character values or conditions that represent the end of segment 
and/or message ar€ dependent en the terminal type. 

In cur subset, 327C terminals only, the physical terminal input will 
always be a single segment message and transmission. The EOS, EOM and 
lor condition will all be set after the enter or program function key 
pressed and the data is transmitted. 



is 



on the output side, a message can be divided into nultiple segments. 
Also an application prcgrai can send different messages to different 
terminals, that is, a message to a printer terminal and a message to the 
input display terminal. Each segment reguires a separate insert call by 
the application program. 

The format of a message segment as presented to or received from an 
application program is shown in Figure 3-2. 




LL : total length of segment in bytes including 

the LL ♦ ZZ fields. 
ZZ : IMS/VS system fields 
DATA : application data 

Pigure 3-2- A Message Segment. 



IMS/VS ONLINE OPIBATICN: CVEBVIEW 

As introduced in Chapter 1, IMS/VS online processing is done with three 
different types of regions, address spaces, or partitions under CS/VS: 

• The control (CTL) jegion contains the IBS/VS control program. It 
controls the terminals and data bases. 

• The message Ergcessing (KEP) region contains a user program for 
message-driven processing of the data bases. The MPP region is 
controlled ty and relies upen the CTL region. The application 
prcgram which execute in the MEF region is called a message 
E£2cessing EE59£§5 21 JJEF> Different MPPs can be subsequently 
loaded and activated in a single MPP region. 
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• The batch message processing (BMP) l§gion contains an application 
Frogram for~batch processing of the data bases managed by the CTL 
region. Application programs executing in a BMP region are called 
batch message processing programs or BMPs. 

Figure 3-3 gives an overview of these 3 region types and the control and 
data flow within them. 
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Figure 3-3- The IMS/VS Regions and Their Control/Data Flow. 

lk£_CTL_Begion 

The CTL region is initiated through an OS/VS start command. The 
terminals, data bases, and the leg tape are all attached to this region. 
A type 2 supervisor call routine is used for switching control 
information, message and data base data to the MPP/BMF region and back. 

The CTL region normally runs as a system task and uses CS/VS access 
methods fcr terminal and data base access. 

Once the CTL region is started, its general data flow is as follows. 
See Figure 3-3. 

1. The input data from the terminal is read by the data communication 
modules. After editing by message format service (MFS) , this input 
data is put in the input gueue (TRAN) , which is seguenced by 
transaction code. 

2. The scheduling modules will start the processing of a transaction in 
an MPP if an MPP is free and other conditions are met. 
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3. Upon request from an MPP/BMP, the DL/I modules pass a message or 
data base segment to or from the MPP/EMP. 

Note: In MVS, the DL/I modules, control blocks, and pools reside in 
the common storage area (CSA) and the CTL region is not needed for 
most EE processing. 

U. The message output from the MPP is put in the output message queue 
JLTEPM) , which is sequenced by logical terminal name. 

5. The communication modules retrieve the message from the output queue 
and send it to the output terminal. MFS is used to edit the screen 
and printer output. 

6. All changes tc the message gueues and the data bases are recorded on 
the log tape. In addition, checkpoints for system (emergency) 
restart and statistical information are logged. 

Notes : 

1. The physical logging modules run as a separate task and use 
OS/VS ESTAE for maximum integrity. 

2. The checkpoint identification and the log tape volume serial 
numbers are recorded in the restart data set. 

7. Program Isolation assures data base integrity when two or more 
MFPs/EMPs update the same data base. It also backs out (undoes) 
data base changes made by failing programs,. This is done by 
maintaining a short-ten, dynamic log of the old data base element 
images*. 

8. The control module provides multi-tasking for the above activities- 
These separate functions, that is, input processing, queueing, MFF 
processing, data base call processing, output processing, etc., can 
be executed asynchronously for multiple transactions. However, they 
will be executed in sequence for a unique transaction occurrence. 
The OS/VS event facility is used for the control of the 
multi-tasking and input/output operations. 

An MPP region is started with an IMS/VS command. The CTL region in turn 
issues an OS/VS command to initiate a region via OS/VS job management. 
Message processing application programs (MFFs) are loaded/activated in 
this region as required. They are scheduled by the control region. If 
the application issues DI/I calls to access data bases or terminals, 
these calls are processed in cr under supervision of the control region. 
An MPP region must not use OS/VS data sets because these cannot be 
repositioned during emergency restart. Also, OPEN/CLOSE processing of 
these data sets might cause (performance) problems. 

Ike _BMP_ Region 

A BMP region may contain an application program for processing against 
data bases in the batch manner. The application program in the batch 
region is scheduled by OS/VS job management, but may utilize the DL/I 
facility for data base reference. An application program executed in 
the BMP region can access only IMS/VS data bases that are defined in the 
IMS/VS control region. 
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BMFs can access OS/VS data sets. However, if the BMP uses the extended 
checkpoint/restart facility, these data sets should he defined as GSAM 
data bases. 

RELATIONSHIP OF DB/DC 10 DE SYSTEM 

In general, all the DL/I data base facilties as presented in Chapter 2 
are available in the IMS/VS DB/BC system. The only exception is that 
GSAM data irases (and ether OS/VS files) cannot be used by a cessage 
processing program (MFP). They can be used in a batch message 
processing program (BMP), however. 

Even with an IMS/VS CTL region and related MPF/BMF regions active, a 
batch-only DL/I region can be executed™ This El/I regicn provides the 
same functions as the batch-only system. However, this DL/I region 
cannot Lave access to data bases connected to the CTL region. It should 
therefore only be used for batch processing when the CTL region is not 
active, or for processing data bases that are not used by the online 
system. 

In our subset, we will assume that all batch processing while the CTL 
region is active is done by BMPs, 

TERMINAL INPUT DATA PROCESSING 

Figure 3-U shculd be referred to for the following discussion. 
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Figure 3-4. Input Message Processing 



When IMS/VS reads; data frcm a terminal via the telecommunication access 
method, it first checks the type of input data. 
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InpuJt_flessage_.Ty.pes 

As discussed in Chapter 1, the three basic types of terminal input are: 

• A command, which starts with a slash (/) . 

• An in_ut message , to be routed to an application program fcr 
processing. The program destination is defined by the 1- to 8- byte 
transaction code included as the first part of the input. 

• * JiS§§5SJi §___££* "to I 36 routed to another terminal. The terminal 
destination is defined by the 1 to 8 byte logical terminal nam.g 
included as the first part of the input. "" "~ 

In£ut.Hessa^€_Ofi^iD 

IMS/VS maintains the origin cf an input message. Wnen a message is made 
available to an application program, this origin is also made available 
to that program, via its program communication block (PCB) . This origin 
is the logical terminal name (ITEEM) , which is associated with the 
inputting physical terminal at the time the input is received. 

If more than one ITEEM is defined or assigned to a physical terminal, 
they are maintained in a historical chain; the oldest defined/assigned 
first. Any input from the physical terminal is considered to have 
originated at the first logical terminal of the chain. If, fcr some 
reason (such as security or a stopped LTEEM) , the first logical terminal 
is net allowed to enter the message, all logical terminals on the input 
chain are interrogated in chair seguence for their ability to enter the 
message. The first appropriate ITEEM found is used as message origin. 
If no LTEKM can be used, the message is rejected with an error message. 

Terminal Input Destination 

The destination of the terminal input is dependent upon the type of 
input- 

An input command goes directly to the IMS/VS command processor modules. 
Both the message switch and the transaction input are stored in the 
message queues. The transaction input from the 3270 displays is first 
processed by message format service (MFS) , except when input is from a 
previously cleared or unformatted screen. 

MFS provides an extensive format service for both input and output 
messages. It is discussed in detail later in this chapter. 

Once the input is enqueued to its destination in the message queue, the 
input processing is completed. 

MESSAGE QDEOEING 

All input and output messages in IMS/VS (except command input) are 
queued in message queues. See Figure 3-5. 

Hith this approach, input processing, output processing, command 
processing, and application program processing can, to a large extent, 
be performed asynchronously. This means, for example, that the input 
processing of message A can be done in parallel with the data base 
processing for message E and the output processing for message C. A, B, 
and C can be different occurrences of the same or different message 
types and/or transaction codes. 
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Figure 3-5. Message Queueing. 



The message queues are sequenced by destination. A destination can be: 

• A message processing program (MPP) , that is, for transaction input. 
Ordering is by transaction code. 

• A logical terminal (LTERM) , that is, for a message switch, command 
responses, and output generated by application programs. 

The message queues are maintained in main storage (QFOOL) , with cverf low 
data sets en direct access storage, the gueue data sets. The queue 
blocks in main storage and on direct access storage are reusable. This 
helps to minimize the number of I/Os operations required during 
processing. 

£jJSfie_Siz€ x _Perfojcmance_C en si derations 

Because we will consider only 327C terminals in a mostly interactive 
environment, message queueing will be primarily in main storage. 

Chapter 7 contains detailed guidelines for selecting message queue 
parameters such as fclcck sizes, QPCOL size, queue data set allocation, 
etc. 



UIiSAGE_SCHEDUIING 

Once an input message is available in the message queue, it is eligible 
for scheduling. Scheduling is the routing of a message in the input 
queue to its corresponding application program in the message processing 
partition/region. See Figure 3-$. 
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NOTE: MULTIPLE TRANS-CODES PER PROGRAM ARE POSSIBLE 
Figure 3-6. Message Scheduling. 

The linkage between an input message (defined by its transaction code) 
and an application program (defined by its name) is established at 
system definition time. Multiple transacticn codes can be linked to a 
single application program, but only one application program can be 
linked to a transacticn cede. 

In our subset we will limit outselves to a simple, straightforward 
scheduling algorithm. In principle, it will be FIFO (first in, first 
out) scheduling with nc particular priority mechanism. 

Note: This scheduling mechanism is a general "best-fit" for an initial 
IMS/VS installation. This will not prohibit the introduction of more 
sophisticated algorithms later. To do so would reguire changes only tc 
IMS/VS parameters and would te transparent tc the application programs. 

ScheduJULns_Conditions 

The following conditions must be met for a successful scheduling: 

1. An MPP region must be available. Actually, the termination of an 
MPP triggers the scheduling process. 

2. There must be a transaction input message in the gueue. 

3. The transaction and its program are not in a stopped state. 

U. Enough buffer pool storage is available to load the program 

specification block (PSB) and the referenced data base control 
blocks if not already in main storage- 

5. The data base processing intent does not conflict with an already 
active application program (a BMP for instance). Processing intent 
is discussed in more detail in the following section on data base 
processing intent. 
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If the first transaction code with a ready input message does not meet 
all the above conditions, the next available input transaction is 
interrogated, and sc fcrtb. If no message can be scheduled, the 
scheduling process is stopped until another input message is engueued. 
If the scheduling is successful, the I"MS/VS routines in the dependent 
region load the corresponding MPP and pass control to it, 

Schedulin2_A_EMP 

A EMF is initiated in an OS/VS partition/region via regular CS/VS job 
management- However, during its initialization the IMS/VS scheduler in 
the control region is invoked to assure the availability of the data 
base resources for the SffF- 

£ata_Base_Processing_Inrent 

A factor that significantly influences the scheduling process is the 
intent of an application program toward the data bases it uses. Intent 
is determined by examining the intent list associated with the FSE to be 
scheduled. At initial selection, this process involves bringing the 
intent list into the control region. The location of the intent list is 
maintained in the FSB directory. If the analysis of the intent list 
indicates a conflict in data base usage with a currently active program 
in a MPP or BMP region, the scheduling process will select another 
transaction and try again. 

The data base intent of a program at scheduling time is determined via 
the FEOCGFT= parameters in the ESB. 

With the program isolation feature (see the next section) , IMS/VS 
minimizes possible conflicts during scheduling. 

A conflicting situati-»n during scheduling will only occur if a segment 
type is declared exclusive use (FBOCOPT=E) by the program being 
scheduled and an already active program references the segment in its 
PSB (any PROCOPT) or vice versa. 

Example: If a EMF is executing with a defined PFOCOPT=E for the COSTOMEB 
CRDERs""root segment (see Figure 2-12), then no MFP that references the 
same segment will be scheduled. That is, if the MPP to be scheduled may 
reference the logical PARTS data base (Figure 2-1 U) and its PSB contains 
a SENSEG statement for the concatenated segment, it will not be 
scheduled before the above mentioned BMP has ended. Note: A FSE that 
contains a PCE for a SHISAM segment that has delete sensitivity will be 
scheduled exclusively. This is because the method used by IMS/VS tc 
ensure program isolation cannot be used for SHISAM deletes. Since there 
is no delete flag, a VSAR erase must be done to delete the segment, and 
since IMS/VS uses relative byte addresses as the identification of a 
segment, there is no way to prevent another user from inserting a 
segment with the saire key prior to the time the program which did the 
delete reaches a sync point. 

APFLICA1ICN FFCGFAM PBCCESSISG 

Once an application program is scheduled in a dependent region, it is 
leaded into that region by IMS/VS. 

i? I£J? I2c_§ s s i n g 

After the load of the MPP, it is given control. The normal processing 
steps of an MEF are described below and in Pigure 3-7. 

3. 10 IMS/VS Primer 



CTL 



MSG/BMP 




GU DC-PCB 
GN DC-PCB 

GU DB PCB 
ISRT DB PCB 



ISRT DC-PCB 



Figure 3-7. Basic MEP Fie* 

1.. Retrieve the input message via a DL/I message call. 

2- Check the input message for syntax errors. 

3. Process the input message, requesting necessary DL/I data base 
accesses. 

*4., Send output to the originating and/or other (for example, printer) 
logical terminals via DL/I message calls. 

5. Retrieve the next input message or terminate. 

Eole_cf_th€_PSE 

The program specification block (PSB) for an MPP or a EBP contains, 
besides data base PCBs, one or more PCB(s) for logical terminal linkage. 
The very first PCB always identifies the originating logical terminal. 
This PCB must be referenced in the get unique and get next message 
calls. It must also be used when inserting output messages to that 
LTEBM. In addition, one or more alternate output PCBs can be defined. 
Their LTEBM destinations can be defined in the PCBs or set dynamically 
vith change destination calls. 
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The same DL/I language interface which is used for the access of data 
bases is used tc access the message gueues. 

The principal DL/I message call function codes are: 

• GU, get unigae. This call must be used to retrieve the first, cr 
only, segment of the input message, 

• GN, get next. This call must be used to retrieve second and 
subsequent message segments. 

• ISBT, insert. This call must be used to insert an output message 
segment icto the cutpat message gueue. 

Note: These output message (s) will not be sent until the MEE 
terminates or requests another input message via a get unique. 

• CHNG* change destination. This call can be used to set the output 
destination for subsequent insert calls. 

For a detailed description of the DL/I message calls and guidelines for 
their use, see Chapter 4, "Data Ease Processing," 

Prc2ram_Isolation_and_Pinamic_lo33in3 

When processing DL/I data base calls, the IMS/VS program isolation 
function will ensure data base integrity. 

With program isolation, all activity (data base modifications and 
message creation) of an application program is isolated from any ether 
application program |s) running in the system until that application 
program commits, by reaching a synchronization p,oint # that the data it 
has modified cr created is valid. A synchronization point in our subset 
is established with a get unique for a new input message and/or a 
checkpoint call (BMP only) , cr program normal termination (GCEACK or 
BETURN) . 

Program isolation allows two cr more application programs to 
concurrently execute with common data segment types even when processing 
intent is segment update, add, or delete. 

This is done by a dynamic ergueue/degueue routine which enqueues the 
affected data base elements (segments, pointers, free space elements, 
etc.) between synchronization points. 

At the same time, the dynamic leg modules log the prior data base record 
images between those synchronization points. 

This makes it possible tc dynamically back out the effects of an 
application program that terminates abnormally, without affecting the 
integrity of the data bases controlled by IMS/VS. It does not affect 
the activity of other application program (s) running concurrently in the 
system. 

Hith program isolation and dynamic backout, it is possible tc provide 
data base segment occurrence level control to application programs. A 
means is provided for resolving possible deadlock situations in a manner 
transparent tc the application program. 
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One example of a deadlock occurs in the following sequence of events: 
L Program A updates data case element X. 

2. Program E updates data base element Y. 

3. Program A requests Y and must wait for the synchronization point of 
program fi- 
ll.. Program E in turn reguests X and must wait for the synchronization 

point of proaraa A. 

A deadlock has now occurred: both programs are waiting for each other's 
synchronization point- The dynamic enqueue/dequeue routines of IMS/VS 
intercept possible deadlocks during enqueue processing (in above example 
during enqueue processing of event U). 

Upon detecting a deadlock situation, one of the application programs 
involved in the deadlock is abnormally terminated (pseudo abend). The 
activity of the terminated program will be dynamically backed out to a 
previous synchronization point. Its held resources are freed. This 
allows the other program (s) to process to completion. The transaction 
that was being processed by the abnormal terminated program will be 
saved. The application program is rescheduled if it was an MSE. For a 
BMP region, the job must be restarted. This process is transparent to 
application programs and terminal operators. 

There are two situations where the enqueue/dequeue routines of program 
isolaticn are not used ir processing a data base call: 

1. If PHOCOfI=GC (read only) is specified for the referenced segment (s) 
of the call. 

2. If PROCC?T=E (exclusive) is specified for the referenced segment (s) 
in the call. 

Notice that possible conflicts with exclusive extent are resolved during 
scheduling time and as such cannot occur at call time. 

Notes: 

1. With the GO option, a program can retrieve data which has been 
altered or modified by another program still active in another 
region, and data base changes made by that program are subject to 
being Lacked out. 

2. 5xclus4ve intent may be required for long-running EKP programs that 
do not issue checkpoint calls- Otherwise, an excessively large 
enqueue/dequeue table in main storage may result. 

3. Even when PROCOPT=I is specified, dynamic logging will be done for 
data base changes. The ultimate way to limit the length of the 
dynamic log chain in a BMP is by using the XRST/CHKP calls. The 
chain is deleted at each CHKE call because it constitutes a 
synchronization point. 

U. If, as can occur in our subset, one MPP and one -EME get involved in 
a deadlock situation, the III will be subject to the abnormal 
termination, back cut and reschedule process. 
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Upon abnormal termination of a message or batch-message processing 
application program for ether reasons than deadlock resolution, internal 
commands are issued to prevent rescheduling. These commands are the 
equivalent of a /STOP command. They prevent continued use of the 
program and the transaction code in process at the time of abnormal 
termination. The master terminal operator can restart either or both 
stopped resources. At the time abnormal termination occurs, a message 
is issued to the master terminal and to the input terminal that 
identifies the application program, transaction code, and input 
terminal. It also contains the system and user completion codes. In 
addition, the first segment of the input transaction, in process by the 
application at abnormal termination, is displayed on the master 
terminal. The data base changes of a failing program are dynamically 
backed-out. Also, its output messages inserted in the message gueue 
since the last synchronization point are cancelled. 

Con v er § a t io n a 1_P r o c €s s i jg a, 

-A transaction code can fce defined as belonging to a conversational 
transaction during IMS/VS system definition. If so, an application 
program that processes that transaction, can interrelate messages from a 
given terminal. The vehicle to accomplish this is the scratchpad area 
(SPA). A unique scratchpad area is created for each physical terminal 
which starts a conversational transaction. Each time an input message 
is entered from a physical terminal in conversational mode, its SPA is 
presented to the application program as the first message segment (the 
actual input being the second segment). Eefore terminating or 
retrieving another message (from another terminal) , the program must 
return the SFA to the control region with a message ISRT call. The 
first time a SPA is presented to the application program when a 
conversational transaction is started from a terminal, IMS/VS will 
format the SPA with binary zero's (X'OO 1 )- If the program wishes to 
terminate the conversation, it can indicate this by inserting the SPA 
with a blank transaction code. 

OUTPUT MESSAGE PROCESSING 

As soon as an application reaches a synchronization point, its output 
messages in the message queue become eligible for output processing. A 
synchronization point is reached whenever the application program 
terminates or requests a new message/SPA from the input queue via a GU 
call. 

In general, output messages are processed by message format service 
before they are transmitted via the telecommunications access method. 

Different output gueues can exist for a given LTERM, depending on the 
message origin. They are, in transmission priority: 

1. Response messages, that is, messages generated as a direct response 

(same PCB) to an input message from this terminal. 

2. Command responses. 

3. Alternate output messages, that is, messages generated via an 
alternate PCE. 

Note: The printing of "DFS059 TERMINAL STARTED" messages on the 3270 
printer terminals will be suppressed in cur subset. This is done to 
Frotect preprinted forms. 
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LOGGING AND CHECKfCINT/BESIftBT 

To ensure the integrity of its data bases and message processing, IMS/VS 
uses logging and checkpoint/restart. In case of system failure, either 
software or hardware, IHS/VS can te restarted. This restart includes 
the repositioning of users* terminals, transactions, and data rases- 

Logging. 

During IMS/VS execution all information necessary to restart the system 
in ths event of hardware cr scftware failure, is recorded on a system 
log data set- In our subset, this log data set must be on a magnetic 
tap.e unit. 

The following critical system information is recorded on the log tape 
{see Figure 3-8) : 

The receipt of an input message in the input queue 

The start of an KPJ/BBE 

The receipt cf a message by tne MPP for processing 

Before and after images of data base updates by the MPP/BMF 

The insert of a message into the queue by the MPP 

Ths termination of an MPP/EME 

The successful receipt of an output message by the terminal 

n addition to the above logging, all previous data base record images 
re written to a separate dynamic log. This log information is only 
used for dynamic tack-cut processing of a failing MFP/BMF. As soon as 
the MPP/BMF reaches a synchronization point, the dynamic log information 
of this program is discarded. 

Checkpointing 

At regular intervals during IMS/VS execution, checkpoints are written to 
the log tape. This is to limit the amount of reprocessing required in 
the case of emergency restart. A checkpoint is taken after a specified 
number cf log records are written to the log tape or after a checkpeint 
command. A special checkpoint command is available to stop IMS/VS in an 
orderly manner. 

A special disk restart data set is used to record the checkpoint 
identification and log tape volume serial numbers. This restart data 
set (IMSVS.FDS) is used during restart for the selection of the correct 
restart checkpoint and restart log tape(s). 

Note: Although IMS/VS itself provides for full disk logging/restart 
with the IMSVS.PDS data set, this function is not included in our 
subset. 

Cold Start 

An IMS/VS CTL region cold start is done at the first time you start the 
system. During cold start, we format (initialize) the message queue, 
dynamic log and restart data sets. 
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Figure 3-6. IMS/VS Logging 



Emergency ,. Restart 

In case of failure, IMS/VS is restarted with the log tape active at the 
time of failure- Festart processing will back-out the data base changes 
of incomplete MPPs and BMPs. The output messages inserted by these 
incomplete MFEs will be deleted. 

After back-out, the input messages are re-enqueued, the MPPs restarted 
and the pending output messages are (re) transmitted. If a,E»F was 
active at the time of failure, it must be resubmitted via OS/VS job 
management* If the BMP uses the XRST/CHKP calls, it must be restarted 
frcm its last successful checkpoint. In this way missing or 
inconsistent output is avoided. For more details, see Chapter 8, 
"Operations. " 

Normal restart or warm start is done from a previous normal IMS/VS 
termination. The message gueues are preserved in this way. 

SICOEITY 

In our subset we will only consider password and terminal security. For 
a description of these security provisions, see the "IMS/VS Security 
Maintenance Utility" descripticn in Chapter 7, "Installing IPS/VS." 

IMS/VS itself has mere extensive security features for user signon and 
support of user exits and the BACF program product (OS/VS2 MVS only) - 
For more details en these additional security features, see the IMS/VS 
5§B§£5l Ifil2E5§tign manual and the IMS/VS System Application Design 
Guide! 
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THE MASIEB TERMINAL 

The IMS/VS master terminal in cur subset consists cf two components: 

• The primary components, a 327C display terminal of 1920 characters 

(24 lines by 80 columns). 

• The secondary component, a 3270 printer terminal- 
All messages are routed to both the primary and secondary components. 
Special MFS support is used for the master terminal. The display screen 
of the master terminal is divided into four areas. See Figure 3-9. 



MESSAGE AREA (10 lines) 



'//////. B^NK Y/////////////////////^^^^ 



COMMAND OUTPUT DISPLAY AREA (10 lines) 



'/////. 



WARNING MESSAGE AREA (1 line), 
USER INPUT AREA (2 lines) 



'///////////////////////. PASSWORD Y/A 



Figure 3-9. 3270 Master Terminal Format 



The message area is for IMS/VS command output (except /DISPLAY and 
/REISELAY), message swatch output, application program output that uses 
a message output descriptor name beginning with DFSMO (see MFS), and 
IMS/VS system messages. 

The display area is for /DISPLAY and /^DISPLAY command output. 

The warning N message area is for the following warning messages: PASTES 
LINES BAITING, MASIEB MESSAGE WAITING, DISPLAY LINES WAITING, and USER 
MESSAGE WAITING. Io display these messages or lines, press PA1. An 
IMS/VS password may also be entered in this area after the "PASSWCFD" 
literal. 

The user input area is for cperatcr input. 

5E29£5i-.i3B£^i2S-J5§y. 1 1 or PA2 reguests the next output message and 
program"! unction key 12 reguests the Copy function if it is a remote 
terminal. 

For more details on the use of the master terminal refer to Chapter 8, 
"Operations." 
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IMS/VS always has a comnunication path with the OS/VS system console. 
The write-to-operator (WTO) and write-to-operator-with-reply (WTCB) 
facilities are used for this. Whenever the IMS/VS CTL region is active, 
there is an outstanding message requesting reply on the OS/VS system 
console. This can he used to enter commands for the CTL region. £11 
functions available to the IMS/VS master terminal are available to the 
system console. The system console and master terminal can be used 
concurrently, to control the system. Usually, however, the system 
console's primary purpose is as a backup to the master terminal. The 
system console is defined as IMS/VS line number one during system 
definition. 

327C REMOTE CCEI FOHCTICK 

For remote 327C display terminals IMS/VS provides a copy function. By 
pressing EFK12 (PA3 on- data entry keyboard) , the operator can cause the 
contents of the screen to be copied to a printer attached to the same 
control unit. Which printer is selected is determined by terminal 
status and system definition sequence. In general the first ready 
terminal on the control unit is selected. This function should only be 
used for occasional hard copies. For production applications it is 
generally better to perform printing under application program control. 

MESSAGE SWITCHING 

The basic format of a message switch is the destination ITERM name 
followed by a blank and the message text. In our subset, using 3270s 
and message fcrmat service, we will include a sample message switch 
fcxmat. The advantage of using the sample format, is that it 
automatically provides the originating ITERM name and location. The use 
of this format is discussed in detail in the IMS/VS Irimer Remote 
liUSiJBlI 5£eiii2ll§ Guide. 

5ISS AGE_!QRMAT_SERVICE_CVERVIEW 

Through the Message Format Service (MFS) , a comprehensive facility is 
provided for IMS/VS users of 3270 and ether terminals/devices. MFS 
allows application programmers to deal with simple logical messages 
instead of device dependent data. This simplifies application 
development. The same application program may deal with different 
device types using a single set of editing logic while device input and 
output are. varied to suit a specific device. The presentation of data 
on the device or operator input may be changed without changing the 
application program. Full paging capability is provided for display 
devices* This allows the application program to write a large amount of 
data that will be divided into multiple screens for display on the 
terminal. The capability to page forward and backward to different 
screens within the message is provided for the terminal operator. The 
conceptual view of the formatting operations for messages originating 
from or going to an MFS-supported device is shewn in Figure 3-10. 



3.18 IMS/VS Erimer 



/mfs 

/ supported 

\device 




APPLICATION 
PROGRAM 



DEVICE 
INPUT 



INPUT 
MESSAGE 



OUTPUT 
MESSAGE 




MFS 

SUPPORTED] 

DEVICE 



DEVICE 
OUTPUT 



Figure 3-10. Message Formatting Using MFS 

MFS has three major components: 

• MFS language utility 

• MFS pool manager 

• Message editor 

The MFS language utility is executed offline to generate control blocks 
and place them in a format control block data set named IMSVS. FCFM4T. 
The control blocks describe the message formatting that is to take place 
during message input or output operations. They are generated according 
to a set of utility control statements. There are four types of format 
control blocks: 

• Message input descriptor (MID) 

• Message output descriptor (MCD) 

• Device input format (DIF) 

• Device output format JDCF) 

The MID and MOD blocks relate to application program input and output 
message segment formats, and the CIF and DOF blocks relate to terminal 
I/O formats. The MID and DIF blocks control the formatting of input 
messages, while the MCC and DCF. blocks control output message 
formatting. 

No t es : 

1. The DIF and the DOF control blocks are generated as the result of 
the format (FMT) statement. 

2. The MID and the MOE are generated as a result of different lessage 
(MSG) statements. 

3. The initial formatting of a 327C display is done via the "/FCBMAT 
modname" command. This will format the screen with the specified 
MOD, as if a null message was sent. 

Figure 3-11 provides an overview of the MFS operations. 
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Figure 3-11. Overview of Message Format service 



MFS AND THE 327C 



IMS/VS Message Format Sa 
is always used tc format 
of the 327C information 
device independence for 
application system desig 
capabilities in terminal 
the 3270, its use of MFS 
ether HFS supported tern 
Information Manual for a 



rvice (MFS), described in the previous section, 

data transmitted between IMS/VS and the devicss 
display system. MFS provides a high level of 
the application programmers and a means for the 
ner to make full use of the 3270 device 
operations. Although our subset only considers 
is such that it is open-ended to the use of 
inals when required. See the IMS/VS General 
list of these terminals. 



BELATIONSHIP EETHEEN MFS CONTROL BLOCKS 

Several levels of linkage exist between MFS control blocks, as described 
in the following sections. 

2IS_Cgntrgl_f lock_CkaininQ, 

Figure 3-12 shows the highest-level linkage, that of chained control 
blocks. 
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Legend: 

1. This linkage must exist. 

2. If the linkage does not exist, device input data from 3270 devices 
is not processed by MFS„ It is always used in our subset. 

3. This linkage is provided for application program convenience. It 
provides a MOD name to be used by IMS/VS if the application program 
does not provide a name via the format name option of the insert 
call. The default MOB, DFSH02, will be used if none is specified at 
all, or if the input is a message switch to an MFS-supported 
terminal. 

4.. The user-provided names for the DOF and DIF used in one output/input 
sequence ar€ normally the same. The MFS language utility alters the 
internal name for the DIF to allow the MFS pool manager to 
distinguish between the DOF and DIF. 

The direction of the linkage allows many message descriptions to use 
the same device format if desired. One common device format can be 
used for several application programs whose output and input message 
formats, as seeR at the application program interface, are guite 
different. 

Figure 3-12. Chained Control Block linkage 
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Figure 3-13 shows the second level of linkage, that between message 
fields and device fields- The arrows shew the direction of reference in 
the MFS language utility control statements, not the direction of data 
flow. 

References to device fields by message fields need not be in any 
particular sequence- An MFID need not refer to any DFLD, in which case 
it simply defines space in the application program segment to be ignored 
if the MFID is for output, and padded if the MFLE is for input. Device 
fields need net be referenced by message fields, in which case they are 
established qn the device, but no output data from the output message is 
transmitted to them. Device input data is ignored if the DFLD is not 
referenced by an infut HFLD » 




Figure 3-13. Linkage between Message Fields and Device Fields 

Linkaae^between^LPAGE^Ard^DPAGE 

Figure 3-1« shows a third level of linkage, one which exists between the 
LPAGE and the EPAGF. 
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Figure 3-1U. LPAGE — DPAGE Linkage 



The LPAGE in the MOD must refer to a DPAGE in the DCF. 
DPAGEs need not be referred to from a given MOE. 



However, all 



Because we will always have single segment input in our subset, the 
defined MFLDs in the MID may refer to DFLDs in any DPAGE. Eut input 
data for any given input message from the device is limited tc fields 
defined in a single DPAGE. 



2. it 
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Figure 3-15 shows a fourth level of linkage- It is optionally available 
to allow selection of the MID based on which MOD LPAGE is displayed when 
input data is received from the device- 
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Figure 3-15. Optional Message Description Linkage 



Le a,e n d : 

1. The next MID name provided with the MSG statement is used if no name 
is provided with the current LFftGE. 

2- If a next MIE name is provided with the current LPAGE, input will be 
processed using this nane. 

3. Fcr 327C devices, all MIDs oust refer to the same DIF. This is the 
sane user-prcvided name used to refer to the EOF when the MOD was 
defined. 



Data Communication Desigr. 3.23 



32 70_pevice_Ccnsideraticns_R^ 

Since output to 3270 display devices establishes fields en the device 
using hardware capabilities, and field locations cannot be changed by 
the operator, special linkage restrictions exist- Because formatted 
input can only occur from a screen formatted by output, the IFAGE and 
physical page description used for formatting input is always the same 
as that used tc foLnat the previous output. The MFS language utility 
enforces this restriction by ensuring that the format name used for 
input editing is the sane as the format name used for the previous 
output editing. Furthermore, if the DIF corresponding to the previous 
DCF cannot fce fetched during online processing, an error message is sent 
to the 327C display. 

UIS_ FUNCTIONS 

The following sections contain a description of the basic MFS functions. 

INPUT MESSAGE FORMATTING 

Ml device input data received by IMS/VS is edited before being passed 
to an application program. The editing is performed by either IMS/VS 
basic edit or MFS.. This section describes the input message editing 
performed by MFS. It tells hew the use of MFS is determined and how, 
when MFS is used, the desired message format is established based or. the 
contents of two MFS control blocks — the device input format (DIF) and 
the message input descriptor (MID). 

All 3270 devices included in an IMS/VS system use MFS. The 3270s always 
operate in formatted irede except when first powered on, after the CLEAB 
key has been pressed, or when the MOD used to process an output message 
does not name a MID to fce used for the next input data. While in 
unformatted mode, you can still enter commands and transactions, but 
they will not be formatted by MFS. 

Input data from terminals in formatted mode is formatted based on the 
contents of twe MFS control blocks, the MID and the DIF. The MID 
defines how the data should be formatted for presentation tc the 
application program and points to the DIF associated with the input 
device- See Figure 3-16. 
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Figure 3-16. MFS Input Formatting 
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The MIC contains a list of ff€ssjig^_descrij:tcr fields (MFLDs) which 
define the layout of the input segment as is to be seen by an 
application program. The DIF contains a list of device descr_ip.tor 
fields (DFLDs) which define what data is to be expected from which part 
of the device (that is, the location on the screen). MFS maps the data 
of the DFLDs intc the corresponding MFLDs- The application program is 
largely device independent because different physical inputs can be 
mapped into the same input segment. 

MFLD statements are to define: 

• The device fields (DFLDs) defined in the DIF which contents will be 
included in the message presented to the application program. 

• Constants, defined as literals to be included in the message; a 
common use of literals is tc specify the transaction code. 

In addition, the MFLD statement defines: 

• The length of the field expected by the application program. 

• Left or right justification and the fill character to be used for 
padding the data received frcm the device. 

• A 'ncdata' literal for the MFLD if the corresponding DFLD does not 
contain any input data. 

It should be noted that all message fields as defined by MFLD statements 
will be presented to the applicaticn program in our subset. 
Furthermore, there will always be only one input message segment, except 
for a conversational transaction, in which case the first segment 
presented to the program is the SFA. The SPA is never processed by MFS, 
however. 

IfiI!iii_li®ssa - g€_Fi€ld_Attri^ute_Data 

Sometimes input messages are simply updated by an application program 
and returned to the device. In such a case, it may simplify message 
definition layouts in the MPP if the attribute data bytes are defined in 
the message input descriptor as well as in the message output 
descriptor. 

Non-literal input message fields, can be defined to allow for 2 bytes of 
attribute data. lihen a field is so defined, MFS will reserve the first 
2 bytes of the field fcr attribute data to be filled in by the 
applicaticn program when preparing an output message. In this way, the 
same program area can be ccnveniently used fcr both input and output 
messages. When attribute space is specified, the specified field length 
must include the 2 attribute bytes. 

IMS/V£_£asswcrds 

If the input data is for a password protected transaction, a device 
field should be designated fcr the password. The device field in which 
the operator keys in the password will not be displayed on the screen. 

OUTPUT MESSAGE FCBKfiTTIHG 

All output messages for 3270 devices are processed by MFS in a way 
similar tc input. 
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Out£ut_Data_Fcr§attin2_0sing_MFS 

All MFS output formatting is based on the contents of two MFS control 
blcoks -- the message output descriptor (MOD) and the device output 
format [DO?) • See Figure 3— "1 7 • The HOD defines output message content 
and optionally, literal data to be considered part of the output 
message. Message fields (MFLDs) refer to device field locations via 
device field (DF1D) definitions in the DCF. The DOF specifies the use 
of hardware features,, device field locations and attributes, and 
constant data considered part of the format. 
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Figure 3-17. KFS Cutput Formatting 



The layout of the output message segment to be received by MFS from the 

program is defined by a list of MFLDs in the MOB, The DOF in turn 

contains a list of EFLDs which define where the data is to be 

displayed/printed on the output device, MFS maps the data cf the MFLDs 
into the corresponding DFLDs. 



All fields in an output message segment must be defined by 
statements. Fields can be truncated or omitted by two metho 
first method is to insert a short segment. The second meth 
place a NOLL character (X*3F') in the field. Fields are sc 
(including the attribute bytes, if any) to right for a NULL 
The first NOLL character encountered terminates the field, 
character of a field is a NULL character, no data is sent t 
for this field. This neans that if the field is protected 
device format is used, the old data remains on the screen, 
old data of a protected field the application program must 
to that field. Positioning of all fields in the segment re 
same regardless of NOLL characters. Truncated fields are p 
program tab character in cur subset. Furthermore, we alway 
erase-unprotected-all in the display device format. This e 
data in unprotected fields en the screen. 



KFLD 

ds. The 
od is to 
anned left 

character. 

If the first 
c the screen 
and the same 

To erase the 
send X^03F» 
mains the 
added with a 
s specify 
rases all old 



Notes : 

1. Device control characters are invalid in output message fields under 
KFS. The control characters HT, CE, LF, NL, and ES will be changed 
to null characters (X* CC f ) . All other nongraphic characters are 
changed to blanks before transmission. Graphic characters are X'40* 
through X'FE». 

2. With MFS, the same output message can be mapped on different device 
types with one set of formats. This will not be covered in our 
subset. The formatting discussed will cover one device type per 
device format, not a mixture. However, the mixture car be 
implemented later by changing the formats. 
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In addition to MF1B data, constants can be mapped into DFLDs- These 
constants ar€ defined as literals in DFLD or MFLD statements. 

Multifile -Sejg men t_Out£u t_Messa5.es 

MFS allows mapping of cne cr mere output segment-s of the same message 

onto a single cr multiple output screens. In our subset, we will limit 

ourselves to a one-to-one relationship between output message seoments 

and logical output pages. Alsc, cne logical output page is one physical 
output page (one screen) . 

l£Sical_Fag.ing_of_Cut2ut__f|essa3es 

Logical paging is the way cutput message segments are grouped for 
formatting. When logical paging is used,- an output message descriptor 
is defined with one cr mere LPAGE statements. Each LPAGE statement 
relates a segment produced by an application program to a corresponding 
device page. 

Using logical paging, the simplest message definition consists of one 
LPAGE and one segment description. As shown in Figure 3-18, each 
segment produced by the applicaticn program is formatted in the same 
manner using the corresponding device page. 

MSG Device Application 

l^finition EiU3£ Elfi2I§J8_2ut£St 

LPAGE1 >DPAGE1 Segment 1 

SEG1 

or 

Segment 1 
Segment 1 
Segment 1 

Figure 3-18. In Cutput Message Definition with one LPAGE 

With the definition shown in Figure 3-18, each output segment inserted 
by the MEF will be displayed with the same and only defined MOE/DOF 
combination. 

If different fcrmats are required for different output segments, one 
LPAGE and SEG statement combination is required for each different 
format. Each LPAGE car. link tc a different DPAGE if desired. (This 
would not be v required if only defined constants and MFLDs differ in the 
MOD.) 

The selection of the LPAGE tc be used for formatting is based on the 
value cf a special MFLE in the output segment. This value is set by the 
MPP- If the LPAGE to be used cannot be determined from the segment, the 
last defined LPAGE is used. See also the description of the CCNE 
parameter of the LPAGE statement. Each LPAGE can refer to a 
corresponding DPAGE with unique DFLDs for its own device layout. See 
Figure 3-19. 
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MSG 



LPAGEl 
SEG1 



De vice 



Application 

Segment 1* (LPAGE1 condition specified) 



Figure 3-19, An Output Massage Definition with Multiple Pages 

Q£§]J§3:2 r ._I§2iD9LQ£_ c .utEUt_ Messages 

If an output message contains multiple pages, the operator requests the 

next one with the program access key. I (PA1). If PAt is pressed after 

the last page is received, IMS/VS will send a warning message in our 

subset. If PA1 is then pressed again, IMS/VS will send the first page 
of the current output message again. 

The operator can always request the next output message by pressing the 
PA2 key. Also, in our subset, when the operator enters data, the 
current output message is dequeued. 

Output message fields can he defined to contain literal data specified 
by the user during definition of ths MOD. MFS will include the 
specified literal data in the output message before sending the message 
to the device. 

MFS users may define their c*n literal field and/or select a literal 
from a number cf literals provided by MFS. The MFS-provided literals 
are referred to as system literals and include various date formats, a 
time stamp, the output message sequence number, the logical terminal 
name, and the number of the logical page. 

£S£E!i£-I?i2i£J_iii:ld_Attrifcutjs 

Device field attributes are defined in DFLD statements. For 327C 
display devicas, specific attributes may be defined in the ATTF.= keyword 
of the EF1E statement. If net, default attributes will be assumed. The 
message field definition (MFLD) corresponding to the device field (CFLE) 
may specify that the application program can dynamically modify the 
device field attributes. 

When a field is so defined, the first 2 data bytes of the field are 
reserved for attribute data. Any error in the 2-byte specification 
causes the entire specification to be ignored, and the attributes 
defined or defaulted for the device field are used. 

Note: The two attribute bytes should not be included in the length 
specification cf the device field (DFLD) in the DOF. 

The default attributes for ncn- literal 3270 display device fields are 
alphabetic, net-protected, normal display intensity, and not-modified. 
Literal device fields have forced attributes of protected and 
not-modified and default attributes of numeric and normal display 
intensity. Numeric protected fields provide an automatic skip function 
on display terminals. 
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The positioning of the cursor on the 3270 display device is done in 
either of two ways: 

1. The DPAGE statement defines the default cursor position. 

2- The program can dynamically set the cursor to the beginning of a 
field via its attribute byte. 

Jy.steni_Me ssac[e_FieId 132 70_Eispl ay _Ee vices) 

Output formats for 3270 display devices may be defined to include a 
system message field. If sc defined, all IMS/VS messages except DFS057 
REQUESTED FORMAT BLOCK NOT AVAILAELE are sent to the system message 
field whenever the device is in formatted mode- Providing a system 
message field avoids the display cf an IMS/VS message elsewhere on the 
screen, thereby overlaying the screen data. 

When MFS sends a message tc the system message field, it activat€£ the 
device alarm (if any) but dees not reset modified data tags (MBTs) or 
move the cursor- Since an IMS/VS error message is an immediate response 
to input, MDTs remain as they were at entry and the operator merely has 
to correct the portion of the input in error. 

In our subset we will always reserve the bottom line of the screen for 
the system message field. This field can also be used to enter 
commands, for example, /FCBK£Tu 

E£i££®£-5§3§_?°.£2§t_£92£.E2l 

The 327C printer devices are also supported via MFS. Three basic 
options can be specified in the DEV statement (PAGE= operand) : 

• A defined fixed number of lines should always be printed for each 
page (SPACE). This is the recommended option because it preserves 
forms positioning. 

• Only lines containing data should be p-rinted. Blank lines are 
deleted (FLCAI)- 

• All lines defined by DFlDs should be printed, whether or not the 
DFLDs contain data (DEFN) . 

MFS FCEMATS SUPPLIED BY IMS/VS 

Several formats are included in the IMSVS. FORMAT library during IMS/VS 
system definition- They are used mainly for the master terminal, and 
for system commands and messages. All these formats start with the 
characters DFS. Cne of the most interesting in our subset is the 
default output message format. This format is used for broadcast 
messages from the master terminal and application program output 
messages with no HOD name specified- It permits two segments cf input, 
each being a line on the screen, DFSDF2 is the format name, DFSM02 the 
MOD and DFSMI2 the MID name. 

When the master terminal format is used, any message whose ROD name 
begins with EFSMO (except DFSM03) is displayed in the message area. Any 
message whose MOD name is BFSDSPC1 is displayed in the display area. 
Messages with other MOE names cause the warning message USER MESSAGE 
WAITING to be displayed at the lower portion of the display screen. 
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MFS CCNTBCL SJATEMEKTS 

This section describes the ccntrcl statements used by the HFS language 
utility. Ihere are two major categories of control statements: 

• Definition statements are used to define message formats and device 
formats. 

• Compiler statements are used to control the compilation and, listings 
of the definition statements. 

The definition of message formats and device formats is accomplished 
with separate hierarchical sets of definition statements. The statement 
set used to define message formats consists of the following statements: 

MSG Identifies the beginning of a message 

definition. 

LPAGE Identifies a related group of 

segment/field definitions. 

EftSSKCBD Identifies a field to be used as an 

IMS/VS password. 

SEG Identifies a message segment. 

MFLD Defines a message field. Iterative 

processing of MFLD statements can be 
invoked by specifying DC and FKDDC 
statements. To accomplish interative 
processing, the DO statement is placed 
before the MFLD statement (s) and the 
ENDDO after the MFLD statement (s) . 
See following discussion on 
compilation statements. 

MSGEND Identifies the end of a message 

definition. 

The statement set used to define device formats consists of the 
following statements: 

FMT Identifies the beginning of a format 

definition. 

DEV Identifies the device type and 

operational options. 

DIV Identifies the format as input, 

output, or both. 

DPAGE Identifies a group of device fields 
corresponding to an LPAGE group of 
message fields. 

EFID Defines a device field. Iterative 

processing of DFLD statements can be 
invoked by specifying DC and ENDDO 
statements- To accomplish iterative 
processing, the DC .statement is placed 
before the DFLD statement (s) and the 
ENDDC after the DFID statement (s) . 
See the following discussion on 
compilation statements. 
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FMTENE Identifies the end of a format 

definition. 

Compilation statements have variable functions- The most common ones 
are: 

DO Bequests iterative proc«ssiug of WFLD or DF1E 

definition statements. 

EJECT Ejects SYSPRINT listing to the next page. 

END Defines the end of data for SYSIN processing. 

ENDDC Terminates iterative processing of MFIE or EFLE 

definition statements. 

PRINT Ccntrcls SYSPF.INT options. 

SPACE Skips lines on the SYSFEINT listing. 

TITLE Provides a title for the SYSPEINT listirg. 

Compilation statements are to be inserted at logical points in tiie 
sequence of control statements. Fcr example, TITLE could be placed 
first, and EJECT could be placed before each MSG or FMT statement. 

RELATIONS BETWEEN SOURCE STATEMENTS ANE CONTROL ELOCKS 

In general, the following relations exists between the MFS source 
statements and ccntrol blccks: 

• One MSG statement and its associated LPAGE r SEG, and MFLE statements 
generate one MIE or MCE- 

• One FMT statement and its associated EEY, DIV, EPAGE and DFLD 
statements generate one DIF and/or DOF. For displays, both the DIF 
and DOF are generated, because the output screen is used fcr input 
too. 

In addition the MFS utilities will establish the linkages between the 
MID, BOD, DIF, and DOF. These are the result of the symbolic name 
linkages defined in the source statements. 

Naminc|_Conventions 

The names of format blocks must be unique. The MID and BCD names, 
specified as the label of the KSG statement must be 1 to 8 alphanumeric 
characters. The EIF and DOF names are de-rived from the 1 to 6 
alphanumeric character label of the FMT statement. 

With reference to our naming convention in Chapter 1, we will use in the 
samples: 

« OE4aaa for the FMT (DIF/DOF) 

• OEHaaaln for the MID 

• OEUaaaOn for the MOD. 
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where: 
aaa identifies the application 
n is a sequence number 



UTILITY SYNTAX 

The HFS language utility uses the syntax common to Assembler language. 
In addition, it shouia te noted: 

• There is no limit to ths number of continuation cards. 

• There is no limit to the total number of characters in the operand 
field. Individual operand items cannot exceed 256 characters. 

• Literal length restrictions do not- include leading, trailing, and 
imbe4ded second quote characters. 

• If a nonstandard character, such as a multipunch, is detected in a 
literal, a severity 4 warning message is issued. 

■• Positional parameters, if specified, must precede keyword 
parameters. 



KFS DEFINITION STATEMENTS 



Following is a detailed description of each of the MfS language 
definition statements. This description should be used as a reference 
when you are coding your own formats. You can skip this section at 
initial study. A coding sample is provided in Figure 3-21 at the end of 
this section. 



MSG Statement 

The MSG statement initiates and names a message input or output 
description. 

/ - 



label 



MSG 



["TYPE-flNPUT 
|_ [O0TP0 1 



,SOR= (formatname,IGNOBE) ,CPT=2 
[ ,NXT=msgdescriptionnaae ] 
FOR MSG TYPE-O0TP0T ONLY 
,PAGE=YES 
i. ...... ........ . ...... ..-.j 



label 

a 1- to 8-character alphameric name dust be specified. This label 
may be referred to in the NXT operand of another message 
description- It is the name of the MID or MOB which are stored in 
the IMSVS.BORMAT library. 
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TYPE= 

defines this description as message INPUT or OUTPUT, 
is INPUT, 



Default value 



SOE= 

f crmatname is the name of the FMT statement which, with the DEV and 
DFLD statements, defines the terminal data fields processed by this 
message description. IGMCBE should be specified as shown in our 
subset. 

CPT=2 

should be specified as shown in our subset. 

NXT= 

specifies a message description to be used to map the next expected 
message as a result of processing a message using this message 
description. If IYPE=INPUI, NXT= specifies a message output 
description- In that case, the MOD can be overridden by the 
application program. If TYFE=OUTPUT, NXT= specifies a message input 
description. 

If TIFE=CUTPUT and the formatname specified in the SOF- operand 
contains formats fcr 3270 and/or 3270P device types, the 
msgdescripticn name referred tc by NX1=, (the message input 
description) must use the same formatname. This parameter should be 
coded if TYPE=OUTPCT. 

FAGE=YES 

should be specified as shown in our subset for all output message 
descriptions. 

IJEiGJ Statement 

The LFAGE statement defines a group of segments comprising a logical 
page. Ihe IPAGE statement is optional and in our subset only applicable 
to output messages. 

/ — --, ,--.., 

LPAGE I SOE=dpagename 

[ ,COND= (mfldname, = , , value' ) ] 
( ,NXT=msgdescriptionname ] 

L- ---------- --„-.---_--.--,.-----,.---.--..-_------, j 



S0P= 



specifies the name of the DPAGE statement that defines the display 
fcrmat fcr this logical page. 



CCND= 

this parame 
tc be used 
name of an 
be egual to 
as follows: 
value, then 
description 
character f 
Example: C 
one charact 
LPAGEs fail 
ires sage. 



ter controls the selection of the message output formats 
for each logical page occurrence. Mfldname must be the 
MFLD defined in this LPAGE . The langth of this FFID must 
the length of the value literal. This parameter works 
If the content of the mfldname is egual to the specified 
this IFAGE and its associated segment, field, and format 
are used for fcrmatting of the output message. A one 
ield with values A, E, C,..., etc., is recommended. 
CKDMFAGETYFE^^A') , where FAGETYPE is a defined MFLD cf 
er in this IPAGE. If the conditional tests for all 
, the last defined IPAGE is used for formatting of the 
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NXT = 



specifies the name of the message description to te used to irap the 
next message if this logical paqe is processed. This name will 
override any NXT= name specified on the previous MSG statement. 



PASS«CFD Statement 

The FASSfcCBD statement identifies a field to be used as an IMS/VS 
password, When used, the PASSWORD statement and its associated MFLD must 
precede the first SEG statement in a MSG definition. The total password 
length may not. exceed € characters. The first 8 characters of data 
after editing will be used for the IMS/VS password. 



I ! 

IERSSSCBB j 



Elanks or comments 



-IQ Statement 

The SEG statement delineates message segments and is required only if 
multisegment iressage processing is used by the application program. 
Output message segments processed by MFS cannot exceed the logical 
record length cf the long message queue data set. This maximum is in 
cur subset 1368 bytes. Only one segment should be defined for 
TYFE=INPUT MSGs, and each LFAGE statement. 



/ 



SEG 



£0 Statement 

The CO statement causes repetitive generation of MFLD statements between 
the DC and ENDDC statements. 




count 

specifies ho* many times to generate the following EFID 
statement <s) - The maximum count that may be specified is 99. 



SDF = 



specifies tbe 2-digit suffix to be appended to the BFLD label and 
dfldname of the first group of generated MFLD statements. Default 
value is 01. MFS increases the suffix by 1 on each subsequent 
generation of statements. 

If the specified suffix exceeds 2 digits, MFS uses the rightmost 2 
digits. 
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If the specified count is such that the generated suffix eventually 
exceeds 2 digits, MFS reduces the count to the largest legitimate 
maximum value. For exasrple, if count eguals 3 aBd SUF=95, invalid 
suffixes of 100,101, and 102 would result. In this instance, MFS 
reduces the count to 5, processes the statement, and issues an error 
message. 

MFLD STATEMENT 

The MFLD statement defines a message field as it will be presented to an 
application program as part of a message input segment or received from 
an application program as part of a message output segment. At least 
one MFLD statement must be specified for each BSG description. 



/[label] 



I 
MFLE | FOB MSG TYPE^INPCl 



dfldname 
•literal* 
(jdfldname,' literal*) 



[ ,LTH=nn] 



,JUSI=jL 

B 



,atte=Jhc 

(YES 



,FILL=<NULL 
C»C« 



FCF KSG TYEE=0UTP0T 



dfldname 1 

(dfldname, 'literal') 
_Udf ldname, system-liter a 1)J 



[ r LTH=nn] 



t ATTE= {f§ s }] 



label 

a 1- to 8-character alphameric name may be specified. This label is 
required if it is referred to in the CONE operand of the previous 
LPAGE statement. It may be used simply to uniquely identify this 
statement. If the MF1C is between the CO and INDDO statements, this 
label shculd te restricted tc 6 characters or less. DC statement 
processing appends a 2-digit suffix to the label and prints the 
label as part of the generated MFLD statement. 
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dfldname specifies the device field name (defined via the DEV or DFID 
statement) frcm which input data i& extracted or into which output data 
is placed- If this parameter is omitted when defining a message output 
descriptor, the data supplied by the application program is not 
displayed on the output device- If the repetitive generation function 
of MPS is used (DO and ENDDO statements) , this dfldname should be 
restricted to 6 bytes maximum length. When each repetition cf the 
statement is generated, a 2-character seguence number (01 to 99) is 
appended to the dfldname. If the dfldname specified here is greater 
than 6 bytes and repetitive generation is used, the dfldname is 
truncated at 6 characters and a 2-character seguence number is appended 
tc form an 8-character name- No error message is provided if this 
occurs. This parameter may be specified in one of the following 
f crmats: 

dfldname 

identifies the device field name from which input data is extracted 
or into which output data is placed. 

•literal* 

may be specified if a literal value is to be inserted in an input 
message. 

(dfldname, •literal 1 ) 

If TYPE^OCTPQT, this describes th* literal data to be placed in the 
named DFLE- When this form is specified, space for the literal must 
not be allocated in the output message segment supplied by the 
application program- Normally, such a literal should fc€ defined 
with a DFLD statement. Specifying it in the MCE allows different 
literal values (in different MQDs) to be displayed with the same 
device format. 

If TYPE=INPUT, this describes the literal data to be placed in the 
message field when no data for this field is received from the 
device. 

In both cases, if the LTH= operand is specified, the length of the 
literal will be truncated or padded as necessary to the length of 
the LTH= specification. If the literal length is iess than the 
defined field length, the literal is padded with tlanks if 
TYPE^ODTPDI and with the specified fill character (FILL=) if 
1YPE=INPGT. If no fill character is specified for input, the 
literal is padded with blanks (the default value). The literal 
length may not exceed 256 characters. 

(df Id name, system-liter al) 

specifies, a name from a list of system literals. I. system literal 
functions like a normal literal except, that the literal value is 
created during formatting prior to transmission to the device. The 
LTH= and AITB= operands may not be specified. When this form is 
specified, space fcr the literal must not be allocated in the output 
message segment supplied by the application program. 
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The system literals and their associated length and format are: 



i : 

SYSTEM | PRODUCES LITERAL OF j 
LITERAL | — 1 



NAME | LENGTH | FORMAT 


| COMMENTS 


L1NAME 


I 

e 


aaaaaaaa 


I 

! See 


note 1 


TIME 


I e 


HH:MM: SS 


I 




DATE1 I 


6 


YY.DDD 


t 




EATE2 


I 8 


MM/DD/YY 


I 




DATE3 


A 


DD/HM/YY 


I 




EATEU 


! e 


YY/MM/DD 


I 




LPAGENO | 


l 


nnnn 


ISee 
! 


note 2 



L------------------------.------ ..-..-.., -J 



Notes: 



1. Messages generated by the IMS/VS control region in response to 
terminal input (error messages, most command responses) will 
use DJSM01 and hav€ an LTNAME of blanks. 

2. LPAGENO specifies that the current logical page number of the 
message be provided as a system literal. The literal produced 
will be a U-digit cumber with leading zeros converted to 
blanks.. 

LTNAME is the logical terminal (LTESM) name of the LTERM for which 
this message is being formatted. 

Note: In our subset, the first MFLD in the MID must define the system 
message field used for command input. Ihis complies with our IMS^VS 
££iffi€£ JL§JS°.£i= Terminal Oc.erator.is Guide. Ihe following KFlD(s) in the 
MID must define the transaction code. Ihis can be a literal, EFID(s), 
or a combination- The total length in the MID must be 9 characters, 8 
for the transaction code, and cce blank as delimiter. If necessary, the 
transaction code must be padded with blanks. 

LTH= 

specifies the length of the field to be presented to an application 
program en input or received from an application program on output. 
Default or minimum value is 1 if it is not a literal. Maximum value 
is 8000. The maximum message length must not exceed 32767. In our 
subset, the maximum output segment length is 1388. 

JUST= 

specifies that the input data field is to be left- justified (!) or 
right- justified (R) and right or left truncated as required, 
depending upen the amount cf data expected by the device format 
descriptor. Default value is L. R is recommended for numeric 
fields and L for ether fields. 

ATTR= 

specifies whether (YES) or hot (NO) the first 2 bytes of this field 
should te reserved fcr attribute data tc be filled in by the 
application program (TYFE=CUTP0T) . Default value is NO. Reguests 
that can be made in the field attribute data are described in 
Chapter U under the topic "Dynamic Attribute Modification and Cursor 
Control." These twe bytes must be included in the LTH= operand 
value. AITR=iES is invalid if a literal value has been specified 
through the pcsiticnal parameter in an cutput message. 
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FILL= 

specifies a charactsr to be used to pad this field when the length 
of the data received fret the device is less than the length of this 
fi«ld« This character is also used to pad when no data is received 
for this field. This operand is only valid if TYPE=INFOT. Default 
value is clack. 

C«c» 

character 'c* will be used to fill fields- Reccmmended: Zero 
for numeric fields that are right justified, and blank for all 
ethers. 

NCII 

must fee specified in cur subset for the first HFLD, the system 
message field used for command input. This will completely 
suppress the field if no command input is received. 

ENDDO Statement 

The ENDDO statement terminates the group of HH E statements that are to 
fee repetively generated. The generated MFLD statements are printed 
immediately following the INDDC statement. 

/ ! ! I 

/ | ENDDO ) Elanks or comments | 



MSGEND Statement 

The KSGENt statement terminates a message input or output description 
and is required as the last statement in the description. 

/It ] 

/ | MSGEND | Blanks or comments j 

i ; i i 



IMT Statement 

This statement delineates ard names a device format which defines data 
formats as they are received from or displayed on specific devices. A 
device format is referred to by message descriptions to format input or 
output messages for an application program. 



_, . n 

/ 1 I I 

/ label | FMT | Elanks or comments j 



label 

a 1 - to 6 -character alphameric name must be specified- This name is 
referred tc fcy message descriptions in the SOP= operand of MSG 
statements. 
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This name becomes part cf the member name used for the resulting 
device output fornat and device input format blocks that are stored 
in the IMSVS.FCBMAT library. 

DEV Statement 

The DEV statement defines device and data characteristics for a specific 
device type. The DFLD statements following this DEV statement are 
mapped using these characteristics until the next DEV or FMTEND 
statement is encountered. In cur subset, we will not consider mixing of 
device types, so cnly one DEV statement per FMT should be coded. 



/ 




FOR 327C DISPLAYS 
TYPE=327C-An 

,FEA1=IGN0RE,DSCA=X' 00A0' 
[ ,SYSMSG=dfldlabel] 

FCB 3270 EEINTEFS 

TYEE= {3270E, 2 ) 
1 



,FIAT=IGSCFE 



,PAGE= ( fj 55 



jnumberj_ 



DEFN ] 

FLOAT 

SPACE 



TYPE= 



specifies the 327C display screen size or printer model. 



Based on the display screen size or printer model used, specify: 

TYPEf for Screen _size/Frint€r r ,moQel 

327C-AT 12x80 

3270-A2 2<»xeC 

327C-A3 32x8-0 

3270-A4 «43x6C 

327C-A5 1*2x40 

3270-A6 6xUC 



3270E, 1 



326U-1 
3284-3 
3 2 66-1 



attached to a 3275-1 



327XP,2 



3284-2 

3250-3 attached to a 3275-2 

3286-2 

3267 

3288 

326S 
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Notes: 

1. The IBM 3270 Information Cisplay System provides a hardware 

compatibility fcr displaying a small screen size format on a large 
screen display. A 24x80 screen format will be displayed en the top 
part of a 22xSC or G?x€C display, whether or not that display 
station was defined as a 2Ux80, a 32x80, or a 43x80 display type to 
IMS/VS. Also, a 12x40 screen format will be displayed on the top 
left part of a 12xSC display unit. 

2- If ycu are an existing IMS/VS user, using TYPE= (3270, 1) or 

TYPE= (327C, 2) , you dc net need to change your existing formats. 
They are still valid and are equally subject to note 1 above. 

FEA?=IGNCBE 

should bs specified as shewn in our subset. 

DSCAsX^OOAC 1 

should be specified as shown in our subset. It forces the erase 
unprotected all cpticn. 

SYSMSG* 

specifies the label of the EFLD statement (s) that defines the device 
field in which IWS/VS system messages are to be displayed. A DFLD 
with this label must be defined for each DPAGE. EFLDs for SYSMSG 
should normally be at least ITH=79 to prevent message truncation. 
We will always reserve the last line of each screen for this 
purpose. As we will also use this field for command input, it 
should net be protected (see the DFLD statement) . 

PAGE= 

number 

defines the ruafcer cf print lines on a printed page. This 
value is used for validity checking. The number specified must 
be greater than cr equal to 1. Default value is 55. 

DEFN 

specifies that lines are to be printed as defined by DFLD 
statements (no lines are to be removed or added to the output 
page) . 

SPACE 

specifies that each output page will contain the exact number 
of lines specified in the •number' parameter. This is the 
recommended opticn. 

FLOAT 

specifies that lines with no data (all blank or NULL) after 
formatting are tc be deleted, that is, will not be printed.. 

CIV Statement 

The DIV statement defines device formats within a device format 
description. The formats are identified as input, output, or both input 
and output. Only cce DIV statement per DEV is allowed. 

., , 1 

/ I I I 

/ | DIV I TIPE={lNOUT \ | 

| \ | IcOTPUTj | 

III I 
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TYPE = 

in our subset, INOCT shculd be specified for display (DEV 
TYPE=327C-an) and CUTJUT for printers (EEV TYPE=3270P). 

5££GE Statement 

The DFAGE statement defines a physical page- This statement can be 
omitted if none cf the message descriptors referring to this device 
format (FMT) contain LFAGE statements, and cursor position is under 
program control.. 



/ I 

/ [label] J 



EPAGI ! [CW?SOB=nilrCC) ) ] 



label 

a 1- to 6-byte alphameric name may be specified. This name can be 
emitted if there are no message descriptions for this device forirat 
that contain LPAGE SOE= references, or if only one DPAGE statement 
is defined for the device. 

CDBSCB= 

specifies the position cf the cursor en the screen. The value 11 
specifies line number and cc specifies column. Both 11 and cc must 
fce greater than or egeal tc 1. The default 11, cc value for 
DEV=327C-An is 1,2. Value 1,1 is invalid for screens. 

Ncte: lypically, the cursor position would be controlled ty the 
program via the attribute byte in the reguired field. The cursor 
position via the DPAGE is used for initial formats, requested via 
the /FCFKAT cemmando 

DO Statement 

The DC statement causes repetitive generation of EFLD statements between 
the DO and INDDO statenents. when DO is used, there are restrictions in 
the naming of DFLDs (refer to "DF1E Statement"). 



DO 



ccunt 



1 



line-increment 



,SUF= 



OJ 11 

numberJJ 



i -..-.-- -----.-« ..j 



count 

specifies how many times to generate the statement (s) . 

line-increment 

specifies how much to increase the line position after the first 
cycle, the first cycle uses the 111 value specified in the POS= 
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keyword of the DFLD statement. Default value is 1. 
position is not incremented in this way. 



The column 



S0F= 



specifies the 2-digit suffix to. be appended to the dfldname of the 
first generated DF1E statement. Default value is 01, MFS 
increments the suffix by cne on each subsequent DFLD statement 
generation. 

If the specified suffix exceeds 2 digits, MFS uses th€ rightmost 2 
digits. 

If the specified count is such that the generated suffix eventually 
exceeds 2 digitsf HFS reduces the count to the largest legitimate 
maximum value. For example, if count equals 8 and SCF-95, invalid 
suffixes of 100 , 10 t, and 1C2 would result. In this instance, NFS 
reduces th€ count to 5, processes the statement, and issues an error 
message. 

The DFLD . ^atement defines a field within a device format descriptor 
which is read from or written to the terminal. Only those areas which 
are of interest to the application program should be defined. Null 
space in the format need not and should not be defined. 



/ 



label 



FCB DEV TTPE=3270-An 
[•literal*, ] 
ECS= (lll,ccc) 
[ ,LTH=nnn] 



f,ATTR= ([(ALPHA]! J NOP 
L LlNUM J J JPRO 



NOPfiCT 
PEOT 



' f NORM i 

Jncdisp 

, I HI \ 



FOE DEV TYPE=327CP 
[ 'literal',] 
POS=(lll,ccc) 
[ ,LTH=nnn] 



label 

a 1- to 8-character alphameric name may be specified. This label 
(dfldname) can be referred tc by a message descriptor in 
transferring data to and from a terminal. If the repetitive 
generation function of NFS is used (DO and F.NDDG statements) , this 
dfldname should be restricted to 6 characters maximum length. Khen 
each repetition of the statement is generated, a 2-character 
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sequence cumber (01-99) is appended to the dfldname. If the 
dfldname specified here is greater than 6 characters and repetitive 
generation is used, the dfldnaoe is truncated to £ characters, and a 
2-character sequence number is appended to form the 8-charaeter 
name. Ho error message is provided if this occurs. The label 
should re omitted fcr literals. 

•literal 1 

specifies a literal character string to be presented to the device. 
The literal- length cannot exceed 256 characters for 3270 display 
devices and the lice width -1 fcr 3270 printer devices. 

For DEV TYPE=227C-An, literal fields will have the FHCT attribute 
whether specified cr not. The NOM attribute will be assumed if 
ALPHA is not specified. A literal field cannot be referred to by a 
message descriptor. 

FOS= 

defines the first data position of this field in terms of line fill) 
and column (ccc). Ill and ccc must be greater than or equal to 1. 

For a IYFE=3270-An device, fOS=(1,1) cannot be specified. Fields 
cannot fc€ defined such that they wrap from the bottom to the top of 
the display screen. 

A 3270 display screen cannot be copied when a field starting on line 
1, column 2, has bcth alphabetic and protect attributes. 

LTH= 

specifies the length of the, field. The specified LTH= cannct exceed 
the physical page size cf the device. 

Note: POS= and L3L= do not include the attribute character position 
reserved for a 327C display device. The inclusion of this byte in the 
design cf display formats is necessary since it occupies the screen page 
position preceding each displayed field even though it is not 
necessarily accessible by an application program. 

when defining DFlDs for 3270 printers, a hardware ATTRIEUTE character is 
not used. Therefore, fields may be defined with a juxtaposition that 
does not alien for the attribute character. However, the last column of 
a print line cannot be used. It is reserved for carriage control 
operations performed by IMS/VS. 

ATTE= 

defines the display attribute cf this field. This parameter is only 
applicable tc displays in our subset. Attribute keywords may be 
specified in any crder and only those desired need be specified. 
The underlined keywords reed net be specified since they are 
defaults. Cnly one value in each vertical list may be specified. 

ALPHA 

HUM 

specifies whether cr not the field should have the numeric 
attribute. It is only relevant to input data. The numeric 
attribute specifies that the numeric lock feature and/or 
auto-skip features will be used. For a discussion of numeric 
lock and auto-skip, refer to Oper.ator.Is Guide for IBK 327 
3El2E§§*2££ Plsp^ay Systems, GA27-27427 

HCFECT 

FB01 

specifies whether or net the field is protected from operator 
modification. For literal fields, PEOT is used and 
specification of NOPEOT is ignored. 
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NCFM 

NODISF 

HI 

specifies the field*s display intensity as normal (NORM), high 

intensity 1HI) r cr ncndisplayable (NODTSP) . 

NOMOC 

MCD 

defines whether or not the field modified attribute should be 
assumed for this field. HOD causes the terminal to assume the 
field has been modified by the operator even though it was not. 
This should net be confused with the EROT attribute which 
prevents operator modification. MCD is ignored for literal 
fields. 

Notes: 

1. In general , device fields which should not be changed by the 
operator should have the PRCT attribute. This avoids 
accidental change of such, a field by the operator. Remember, 
the attribute kytes can be set by the MPP. Proper use of this 
can significantly reduce the number of different formats 
otherwise reguired tc meet application needs. 

2. The recommended attribute specification for the system message 
field (see DEV statement) is ATTR=HI. This will display these 
critical messages with high intensity and allow this field to 
be used for command input. 

ODDC Statement 

The ENDDO statement terminates the group of DELE statements that are to 
be repetitively generated. The generated DFLD statements are printed 
immediately following the ENDDC statement. 

/ I I 1 

/ \ ENDDO \ j 

II! I 

«.--------------------------------------■»«------ — -j 



FM1END Statement 

The FMIEND statement terminates a device format description and is 
reguired as the last statement in the device format description. 

/ I J ] 

/ | FMTEND | | 

III I 

t „ ---j 



COMPILATION STATEMENTS 

The following compilation statements are the most frequently used ones 
and are included ir the saifles. 

1111% Statement 

The TITLE statement is used to specify the heading to appear on the 
SYSPRINT listing. 
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/ 



I 1 

! TITLE | •character sequence 1 



•character sequence 1 

specifies the heading tc be printed en the output listing. 

iilil Statement 

The FEINT statement can be used to suppress the detailed output listing 
cf the WFS language processor- It is recommended to include this 
statement at the beginning. 



/ 



\ 

PRINT | NOQEN 
I 



SPACE Statement 

The SPACE statement specifies the number of lines to skip when output is 
printed. The SPACE statement is printed before the skip occurs. 



/ 



I I 

t SPACE f 



4 

number 



J 
number 

specifies hov aany lines tc skip after this statement is 

encountered* Default number is 1- 



EJECT Statement 



The EJECT statement is used to eject a page in an output listing. 
EJECT statement is printed before the actual eject. 



The 



/ 



I I 

| EJECT | 



JJJD Statement 

The ENE statement must be used to define the end of the MFS input 
statements. It must be the last statement. 



Data Communication Design 3.45 



END 



Samgle_Formats 

Figure 3-20 shows the sample formats for the Customer Name Inquiry and 
Address program. The lines illustrate the symbolic linkages between the 
different format blocks and fields- Figure 3-21 shows the screen layout 
of this format as printed by the MPS language utility- The complete set 
cf these KFS source statements is included as member DEUCNI01 in 
IMSVS.FKIKESBC. 



MOD 



OEtCNIOl 


MGS 


TYPE=0UTPUT, 
S0R=(0EfCNI , IGNORE) , 
NXT=0EtCNIIl, 










0PT = 2 




LPAGE 


S0R=A12Q0 




SEG 






MFLD 


CNUM,LTH=b 




MFLD 


CNAM,LTH=20 !^\^_^ 




MFLD 


CADR,LTH=20 \^\T~~^> 




MFLD 


CCTY,LTH=20 X\( 




MFLD 


CPCD , LTH = fa— OON^ 




MFLD 


ERROR,LTH=3 5 \\/\ 




MSGEND ^N^CN. 






MID / \ 


L^OEtCNIIl 


MSG 


TYPE=INPUT,/ 
S0R=<0EtCNI .IGNORE) , 
NXT=0EtCNI01. 
0TP = 2 




LPAGE 


SOR=A12Q0 



TRANSACTION 



CODE 



SEG 

MFLD 

MFLD 

MFLD 

MSGEND 



SYSMSG,LTH=71,FILL=NULL 
•TEtCNINQ • ,LTH=q 
CUSID,LTH = b -^ 



OEtCNI 



A12QQ 



CNUM 



CADR 



CUSID 
SYSMSG 



FMT 
DEV 



DIV 

DPAGE 

DFLD 

DFLD 

DFLD 

DFLD 

DFLD 

DFLD 

DFLD 

DFLD 

DF^LD 

DFLD 

DFLD 

DFLD 

DFLD 

DFLD 

DFLD 

FMTE-ND 

END 



DIF/DOF 

TYPE=3270-A2, 
DSCA=X' OQAO ■ , 

SYSMSG = SYSMSG. — 

FEAT=IGMORE 

TYPE=INOUT 

CURS0R=( (23,20) ) 

'CUSTOMER INQUIRY' ,P0S=<2, 2b) 

'NUMBER' ,P0S=(f ,21) 

POS=(t,33),LTH=b ,ATTR=(HI ,PR0T,NUM) 

' NAME ' ,P0S = (b ,21) 

POS=<b,33).LTH=20,ATTR=CHI .PROT.NUM) 

•ADDRESS' ,P0S=(S ,21) 

POS=<8. 33), LTH = 20,ATTR = <HI, PROT.NUM) 

'CITY' ,P0S=(1D,21) 

POS=<10,33> ,LTH = 2Q, ATTR=(HI , PROT.NUM) 

'POSTAL CODE ' ,P0S=(12,21) 

P0S=< 12 ■ 33) ,LTH = b . ATTR=( HI .PROT.NUM) 

POS=(22,21),LTH=35,ATTR=(HI .PROT.NUM) 

•ENTER CUSTOMER NO * , POS = < 2 3 , 2 ) 

POS=(23,2Q) ,LTH = b,ATTR = HI 

P0S=(2f .2) ,LTH = ?q,ATTR = (HI)^ 



Figure 3-20. Format language Statement Sample 
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ENTER CUSTOMER NO 



CUSTOMER INQUIRY 



NUMBER 



NAME 



ADDRESS 



CITY 



POSTAL CODE 



Figure 3-21. Sample Display Format 



MFS-CONTEOL^EiOCK^GJNEBATION 



MFS control blocks are generated by execution of the MFS language 
utility program. This is a two-stage process. See Figure 3-22. 



STEP 1 



STEP 2 



STEP 3 



MFS 

SOURCE 

STATEMENTS 



DFSUPAAO 



SOURCE 

STATEMENT 

PREPROCESSOR 



DFSUNUBO 



DFSUTSAO 




IMSVS. 
FORMAT 



Figure 3-22. Creation of lis control Hocks 
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The MFS control blcck generaticr can be executed by an IMS/VS supplied 
catalcged" procedure: MFSUTL- lor a description of this procedure, see 
Chapter 7, "Installing IKS/VS." Multiple formats can be generated with 
one execution. In general ycu would process a complete format set, i.e, 
the related message and format descriptions, in one execution of MFSUTL. 
Sample job //SAMP4 25 in IMSVS.PRIMEJOB shows the use of this procedure 
for our sample applications. Three executions of MFSOTL are involved to 
process the three savple format sets. 

STEP 1 

The MFS language utility preprocessor generates intermediate text blocks 
(ITBs) , based on the MFS language source statements. Definitions of the 
MFS language utility source in$ut are, contained in this chapter under 
the topic "MFS Control Statements." The primary function of the 
preprocessor is to perform syntax and relational validity checks on user 
specifications and generate ITBs. The ITEs are then processed by phase 
1 of the utility to generate message (MSG) and format (FMT) descriptors. 
An ITB generated for each MSG and FMT source definition processed and is 
stored ir the historical reference library, IMSVS.REFERAL. An I1B for a 
particular MSG or FMT description can be re-used by the same or another 
format set, once it has been successfully added to the IMSVS.REFERAL 
data set. Each such description must start with a MSG or FKT statement 
and end with a MSGEMD or FMTEHE statement- 

Phase^l. 

The preprocessor invokes phase 1 if the highest return cede generated by 
the preprocesscr is less than 16. Phase 1 places the newly constructed 
descriptors on i:he SEQEIKS data set. Each member processed has a 
control record placed on the SEQBLKS data set identifying the member, 
its size, and the date and time of creation. This control record is 
followed by the image of the descriptor as constructed by phase 1. 
Alternatively, if an error is detected during descriptor building, an 
error control record is placed on the SECBLKS data set for the 
description in error, identifying the member in error, and the date and 
time the error control record was created. In addition, phase 1 returns 
a ccapleticn code of 12 to CS/VS. If execution of step 2 is forced, 
phase 2 will delete descriptors with build errors. 

STEP 2 

Phasj=_2 

Phase 2 receives ccntrcl as a job step following phase 1. After final 
processing, it will place the new descriptors into the IMSVS.FCBKAT 
library. Phase 2 passes a completion code to OS/VS for step 2 based on 
all the descriptor maintenance to IMSVS.FCRMAT for a given execution of 
the MFS language utilitv. 

STEP 3 

In our subset, ae will always execute the MFS service utility after MFS 
control block generation. Ihis utility will build a new index directory 
block which will eliminate the need for directory search operations 
during the IMS/VS online operation. 
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SAMPLE NFS GENEBATIGN JOE 

Job //SAMP425 in IMSVS.PRIMEJOB shows the JCL for the complete MFS 
control block generation process. This job uses the MFSUTL and MFSEVC 
procedures which are placed in IMSYS. PBOCLIE during Stage 2 of IMS/VS 
system definition. The output generated by the second execution of the 
MFS0T1 procedure and the MJSBVC procedure are listed in Chapter 3 of the 
IMS^VS P£ijner. Sample iistijcjs. This is the output of the processing of 
the customer order entry formats. 

MFS LIEBABY MAINTENANCE 

The IMSVS.FOBMAT and IKSVS.FFFEBAL libraries are standard OS/VS 
partitioned data sets. Backup and restore operations can be done with 
the proper OS/VS utility (1EBC0PY) • However, care must be taken that 
both the XMSVS.FCBMAT and the IHSVS. BEFEBSL data sets are dumped and 
restored at_the_sam€_tij6. 

PSBGEN FOB MFFs fiSC EKEs 

^ _ _ .. _ _ _ _ _ _ — — — — — ~ — — — — — *• — — 

As for each DL/I batch program, a FSB is needed for each MPP or BMP. In 
addition to data rase PCBs (see Chapter 2) , a FSB for a MPp/BME contains 
one or mere data communication ECBs. The overall generation of the ESE 
remains as described in Chapter 2. However, there are a few additions 
to the data base PCB statenents, and a new statement for the data 
communication PCB. In addition, you must perform an application control 
blocks generation JACBGEN) for all DBDs and PSBs to be irsed by the"*CTL~ 
region. This'is'discussed at the end of this section. 

ADDITIONAL FSB CODING CCKVEKTICKS 

In addition to the PSB coding conventions stated in Chapter 2, the 
following rules must te observed. 

• The name of the PSE as specified in the PSENAMI= keyword of tbe 
PSEGEN and tfce MBB= keyword in the PSBGEN procedure must be exactly 
the same as the prcgraa lead module name in case of an MPP. This 
name is defined during IMS/VS system definition via the PSB= keyword 
of the APPLCTN statement. 

• The order of the PCBs in the PSB must be: 
1. Data communication PCBs, 

2 Data base PCBs, 

3. GS*M PCEs (not allowed for MPPs) - 

• One data communication PCB is always automatically included by 
IMS/VS at the beginning of each PSE of an MPP or BMP. This default 
data communication PSB is used to insert output messages back to the 
originating IIEBM. 

Note: Ey use of the CKFAT=YES keyword en the batch FSBGEN 
statement, we already provided this PCB to the batch program. In 
this way, a batch program can be ran as a BME without change. The 
relative positions of the data base PCEs remain the same. 
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THE DATA COKfiCNICATICN FCE 

Eesides th€ default data cciniunication PCB, which does not require a PCB 
statement, additional PCBs can be coded* These FCBs are used to insert 
output messages to ITEFKs other than the LTEPM which originated the 
input message, A typical use cf an al!§ina.£e. PCE is to send output to a 
3270 printer terminal. 

The destination of the output ITEBM can te set in two ways: 

• During PSEGEN ty specifying the LTEKM name in an alternate PCB, 

• Dynamically by the MPP during execution, by using a change call 
against a modifiable alternate PCB. 

The method used depends on the PCB statement. 

Z!l§_I£B_Statement 

This is the only statement required to generate an alternate PCB 
(multiple occurrences are allowed) . Its format is: 



/ 



PCB 



TYPE=TF,|LTEFM=name 
|MODlFY=YES 



-.------.--•----_- — -----.- — ----.--«.---- — ----.----.---»•------.. ---j 



Where: 



TYFE=TP 



is required for all alternate PCEs. 

LTEBM-name 
MODIFY=YES 

specifies this is a modifiable alternate PCB (MODIFY=YES) or a 
preset destination alternate PCE, where name specifies the output 
LTERM. MOEIFY-YES is the basic recommendation. 

Note: If HCDIFY=YES is specified, the MPP must specify a valid 
alternate output LTEP.H with a change call before inserting any 
message via this PCB. 

THI DATA EASE PCB 

The data base PCB for an KFF or EMP is basically the same as discussed 
in Chapter 2. Two additional processing intent options can be specified 
with the PRO COP T=key word cf the PCB and/or SENSEG statement. 
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The PB0C0PT= keyword is extended with t'wo additional processing intent 
cpticns, "0" and "E". 

Their meanings are: 

C - Bead only; nc dynairic eroueoe is dene by program isolation for calls 
against this data base- Can be specified with only the G intent 
option, as GO or GOP. This option is orly valid for the PCE 

statement. 

E - Forces exclusive use cf this data base cr segment by the MPP/BMP. 
No other program which references this data base/segment will be 
scheduled in parallel. So dynamic enqueue by program isolation is 
done, but dynamic legging cf data base updates will be done. E can 
be specified with G, I, D, B, and A. 

CACTION: If the 'C 1 option (read-only) is used for a PCB, the data that 
"" is read should net be used as a basis for updating records in 
any data base. Kith this option, IKS/VS does not check the 
ownership of the segments returned- This means that the 
read-only user might get a segment that had been updated by 
another user- If the updating user should then abnormal 
terminate, and te backed out, the read-only user would have a 
segment that did not (and never did) exist in the data base. 
Therefore, the , 0* cption user should not perform updates based 
on data read with that option. An ABEND can occur with 
FB0C0PI=GC if another program updates pointers when this 
program is following the pointers. Pointers are updated during 
insert, delete and backout functions. 

THE PSBGEN STATEMENT 

This is basically the saoe as fcr a data base PCB. The I0EP.0PN= 
parameter must be omitted, the CHPAT=¥ES parameter is ignored. 

EXAMPLE CE AN ONLINE PSB 

Figure 3-23 shews an example of a online PSB. This PSB, PE4C0RDR is to 
be used with the online customer order MPP. Its PSBGEN can be performed 
with job //SAMP401 (COECL) or job //SAMP402 (PL/I) in IMSVS.PEIMEJOB. 
You should compare this PSB with the Phase 2 batch PSB, PE2C0BDR, in 
Chapter 2. 
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K PROGRAM SPECIFICATION BLOCK FOR PHASE 4 

* ORDER UPDATE PROGRAM PE4C0RDR. 
w 

* ALTERNATE MESSAGE OUTPUT TERMINAL 
* 

PCB TYPE=TP,MOOIFY=YES 

k 

* CUSTOMER DATABASE VIEW 

PCB TYPE=DB,DB0NAME=BE2PCUST,PROCOPT=GO»KEYLEN=6 
SENSEG NAME=SE2PCUST 

* ORDER DATABASE VIEW 
* 

PCB TYPE=DB,DBDNAME=BE4L0RDRtKEYLEN=14 
SENSEG NAME=SE20RDER>PROCOPT=AP 
SENSEG NAME=SE20PART , PARENT=SE20RDER , PROCOPT=A 
SENSEG NAME=SE20SHIP,PARENT=SE20RDER,PROCOPT=GI 
* 

* PARTS DATABASE VIEW 
w 

PCB TYPE=DB»DB0NAME=BE4LPART,KEYLEN=20 
SENSEG NAME=SE1PART , PROCOPT=GRP 
SENSEG NAME=SE1PST0K,PARENT=SE1PART,FR0C0PT=GR 



PSBGEN LANG=C0B0L,CMPAT=YES,PSBNAME=PE4C0RDR 
END 

Figure 3*23. Exanple of an Online FSE. 

A£2IjICATICN_CCKTJOI_|ICCK_GEJJB2TION JACEGEN1 

Before PSEs and CBCs can be used by the CTL region, they must be 
expanded to an internal control block format. This expansion is done by 
the Application Control Elock generation (ACBGEN) utility. The expanded 
control blocks are naintained in the IMSVS. ACBLIB. This is a standard 
OS/VS partitioned data set. The OS/VS IEHMOVE and IEBCCPY utilities can 
be used fcr its maintenance. 

JCL FEQOIFEMEHTS 

An ACEGEN procedure is placed in IMSVS. FBOCLIB during IMS/VS system 
definition. Job //SAHP125 in IMSVS. PBIMEJOB shows how to use this 
procedure. 

Note: Multiple BUIIE statements can be coded for both DBDs and PS3s, 
but~the ones fcr DEEs must be first. 

Eeguired^Cont reinstatements 

The utility control statements for this program are free-forir. A 
statement is ceded as a card image and is contained in columns 1—71- 
The control statement may optionally contain a name starting in 
column 1. The operation field lust be preceded by and followed by one 
or more blanks. The operand is composed of one or more PSB/DBO names 
and must be preceded by and followed by one or more blanks. Commas, 
parenthesis, and blanks can be used only as delimiting characters. 
Comments may be written following the last operand of a control 
statement, separated from the operand by one or more blanks. A control 
statement may be continued by inserting a comma after the last operand 
of the statement, inserting a non-blank character in column 72 and 
continuing the statement in column 16 of the next control statement. 
Columns 1-15 of the continuation statement must be blank. 
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In our subset, two control statements are required in the following 
crder: 



| B0T1E 

I 

! EOILD 

I 



DBD= (dbdname,. . - - ) 
FSE> lesbname,-. ..) 



DBD= 



PSB= 



must list all dbdnames cf data bases used by the online IMS/VS 
system- Logical DEDs and GSAK DBDs must not be listed. 

must list all psbnames cf MPPs and BMFs; for example, those defined 
in AFPLCTN statements during IMS/VS system definition. See Chapter 
7. 



lCEC-JN_|xecution 

Only one ACEGEN is required in case of multiple PSE/DBD changes as lcng 
as it is done after the last PS3GEN/DBDGEN and before the CTI region is 
started- 

3HI_DAIA^CCKMCNICATICN_E|S1G^EBCCJSS 

This part of Chapter 3 is complementary to the section "The Data Base 
Design Process" in Chapter 2. It is assumed that you have a clear 
understanding cf Chapter 2 before reading this part. 

He will distinguish between the fcllcwing areas in the IMS/VS data 
base/data communication design process: 

■• Program design 

• Message format service design 

• Data base design 

The data base design process is essentially the same as outlined in 
Chapter 2. Ke will not repeat this, but merely provide additional 
guidelines. 

In the program design section, we will concentrate on the design of 
sessage processing programs (Mils). 

The MIS design will discuss the 3270 screen layouts and operator 
interaction. 

Although we will cover each of the above areas in separate sections, it 
should be realized that they are largely dependent on each ether. 
Therefore, an overall system design must be performed initially and an 
overall system review must follow the design phase of each section. 
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CONCEPTS OF ONLINI TRANSACTION PROCESSING 

In an IMS/VS online environment, one can view a transaction frcm three 
different points: 

• The application, that is, its processing characteristics and data 
base accesses. 

• The terminal user. 

• The IMS/VS system. 

Each of the above constitutes a set of characteristics. A description 
of each set will follow. 

£££lication_Characteristics 

Frcni an application point of view, we can identify: 

• Eata collection with nc previous data base access) . This is net a 
typical IMS/VS application but can be part of an IMS/VS application 
systen. 

• Inquiry (data base retrieve-cnly processing). Inquiry/report 
programs like G3S/VS shculd be considered for this if inquiry is on 
a moze 01 less ad hoc basis. 

• Update. This normally involves data base reference and the 
sutseguent updating cf the data base. This is the environment of 
most IMS/VS applications. 

In a typical IMS/VS multi-application environment, the above 
characteristics are often combined. However, a single transaction 
normally has only one of the above characteristics. 

2iISiS§i_Ult£-£b5E§£i®£istics 

Frcm the terminal user's point of view, we distinguish: 

• Single-interaction transactions- 

• Multi-interacticn transactions. 

The single interaction transaction does not impose any dependency 
between an input message and its corresponding output, and the next 
input message. The multi-interaction transaction constitutes a dialogue 
between the terminal and the message processing program (s). Both the 
terminal user and the message processing program rely on a previous 
interaction fcr the interpretation/processing of a subsequent 
interaction. 

IlSJ^S^Characteristics 

From the IMS/VS system point of view, we distinguish: 

• Non-response transactions. 

• Response transactiens. 

• Conversational transactiens. 
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Note: These IMS/VS transaction characteristics are defined for each 
transaction during IKS/VS system definition. 

With non-response transactions, IBS/VS accepts multiple input messages 
(each being a transaction) frrir a terminal without a need for the 
terminal to first accept the corresponding -output message, if any 
These ncn-response transactions will not be further considered in our 
sample. 

With response transactions, IMS/VS will not accept further transaction 
input from the terminal before the corresponding output message is sent 
and interpreted by the user. 

For conversational transactions, which are always response transactions, 
IMS/VS provides a unique scratch pad area (SPA) for each user tc store 
vital information across successive input messages. 

Transaction Response 1ime_ Considerations 

In addition to the above characteristics, the transaction response time 
is often an important factor in the design of online systems. The 
response time is the elapsed time between the entering of an input 
message by the terminal operator and the receipt of the corresponding 
output message at the terminal. Two main factors constitute in general 
the response time: 

1. The telecommunication transmission time, which is dependent en such 
factors as: 

• Terminal and network configuration 

• Data communication access method and data communication line 
procedure 

• Amount of data transmitted, both input and, output 

• Data communication line utilization 

2. The internal IMS/VS processing time, which is mainly determined by 
the MPP service time. The WPP service _.ime is the elapsed time 
required for the processing of the transaction in the MFP region. 

Chapter 9, "Optimization," contains a basic assessment of the above two 
factors in the section entitled "Data Communication Design 
Optimization." 

chc0sin3_the_Fight_Characteristi.es 

Each transaction in IMS/VS can and should be categorized by one 
characteristic of each of the previously discussed 3 sets. 

Scope combinations of characteristics are more likely to occur than 
ethers, but all cf them are valid. 

In general, it is the designer's choice as to which combination is 
attributed to a given transaction. Therefore, it is essential that this 
selection of characteristics is a deliberate part of the design process, 
rather than determined after inplementation. 
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Following are some examples, based on our sample: 

1. Assume an inquiry for the customer name and address with the 
customer number as input. She most straightforward way to implement 
this is clearly a non-conversational response-type transaction. 

2. The entry of new customed orders could be done by a single response 
transaction. The crder number, customer number, detail information, 
part number, quantity, etc., could all be entered at the same time. 
lhe order would be processed completely with one interaction. This 
is most efficient fcr the system, but it may be cumbersome for the 
terminal user because she or he has to re-enter the complete crder 
in the case of an error. 

Quite often, different solutions are available for- a single application. 
Which cne to choose should be based on a trade-off between systei ccst, 
functions, and user convenience. The following sections will highlight 
this fcr the different design areas. 

ONLINE PKCGBAP DESIGN 

This design area is second in importance to data base design. He will 
limit the discussion of this broad topic to the typical IBS/VS 
environment. Ke will first discuss a number of considerations so that 
you become fairiliar with then. Next, we will discuss the design of the 
two online sample programs. You will notice that some discussions are 
quite arbitrary and may bave to be adjusted for your own environment. 
Do remember, however, that our prime objective is to make ycu aware of 
the factors which influence these decisions. 

SinaJ:e_V€rsus_Multij;le_Passes 

A transaction can be handled with cne interaction or fiass, or with two 
or more passes (a pass is one message in and one message out). Each 
pass bears a certain cost in line time and in IMS/VS and MPP processing 
time. So, in general, ycu should use as few passes as possible. 




ne -Pa ss_ Update : After input validation, the data base updates are all 
performed in the same pass. This is the most efficient way from the 
system point of view. However, correcting errors after the update 
confirmation is received en the terminal requires additional passes or 
re-entering of data. An evaluation of the expected error rate is 
required. 

I*{5j:£Sss_ Ojadate: On the first pass, the input is validated, including 
data base access. A status message is sent to the terminal. If the 
terminal operator agrees, the data base will be updated in the second 
pass. With this approach, caking corrections is generally much simpler, 
especially when a scratch pad area is used. However, the data base is 
accessed twice. 

You should realize, that, except for the SPA, no correlation exists 
between successive interactions from a terminal. So, the data base can 
be updated by semebedy else and the MPP may process a message for 
ancther terminal between two successive passes. 
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U!li£iri&§§_5Et^£§ ; In th is case, each pass does a partial data base 
update. The status of th€ data base and screen is maintained in the 
SPA. This approach should cnly be taken fcr complex transactions, Also, 
remember that the terminal operator experiences response times for each 
interaction. You alsc must consider the impact on data base integrity. 
IMS/VS will cnly back -out the data base changes of the current 
interaction in the case cf prcgrair or system failure. 

Notes: 

1. IMS/VS emergency restart with a complete log tape will reposition 
the conversation. The terminal operator can proceed from the pcint 
where he or she was at the time of failure. 

2. When a conversational application program terminates abnormally/ 
cnly the last interaction is tacked out. 

The application must reposition the conversation after correction. 
For complex situations, IMS/VS provides an abnormal transaction exit 
routine. This is not covered in our" subset. 

Conversational Versus no n-C cry er sat ional 

Conversational transactions are generally mere expensive in terms of 
system cost than ncn-ccnversational ones. However, they give tetter 
terminal operator service. You should cnly use conversational 
transactions when you really need them. Also, with the proper use of 
MFS, the terminal operatcr prccedures sometimes can be enhanced to 
almost the level cf conversational processing. This will te discussed 
in the section atcut MFS Design. 

Basically, the HPP processing can be divided into five phases. See 
Figure 3-24. 
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1. Initialization: The clearing of working storage, which may contain 
data left-over ty the processing of a message from another terminal. 

2. Retrieval of the SPA (optional) and the input message. 

3. Input syntax check. All checks which can be done without accessing 
the data base, including a consistency check with the status of the 
conversation as maintained in the SFA. 

4. Data base processing, preferably in one phase. This means that the 
retrieval of a data base segment is immediately followed ty its 
update. Compare this to an initial retrieve of all required 
segments followed by a second retrieve and then update. 

5. Output processing. The output message is built and inserted 
together with the SPA (only for conversational transactions) , 

Note: After finishing the processing of one input message, the program 
should go back to step 1 and request a new input message. If there are 
no more input messages, IKS/VS will return a status code indicating 
that. At that time, the WPP must return control to IMS/VS. 



Figure 3-24. General MPP Structure and Flow 
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2£§2§§££i2£^l£22£§3_<£ rouging 

It is the designer 1 s choice how much application function will b€ 
implemented by one transaction and/or program. The following 
considerations apply: 

• Inquiry-only transactions should be separated from update 
transactions. These should be normally implemented as 
ncn-conversational transactions. Also, they can be defined as 
"non-recoverafcle inquiry-only" (See Chapter 7, "Installing IKS/VS," 
the TRANSACT macro). If, in addition, the associated MPPs specify 
PR0C0P2-GC in all their data base FCEs, no dynamic enqueue and 
legging will fc€ done for these transactions. 

« Limited-function MPPs are smaller and easier to maintain. However, 
a very large number of KPJs costs more in terms of IMS/VS resources 
(control blocks and path lengths) . 

• Transactions with a leng KPP service tiie (many data base accesses) 
shculd be handled ry separate programs. Chapter 9, "Optimization," 
contains a discussion cf MPP service time and its implications. 

Note: IMS/VS provides a prcgrani-tc-program message switch capability. 
This is net tart cf our subset. Kith this facility, you can split the 
transaction processing in two (or more) phases. The first (foreground) 
MPP does the checking and switches a message (and, optionally, the SFA) 
to a (background) HPP in a lower priority partition which performs the 
lengthy part of the transaction processing. In this way the foreground 
HPP is mere readily available for servicing ether terminals. Also, if 
no immediate response is required from the background HPP and the SPA is 
not switched, the terminal is mere readily available for entering 
another transacticn- 

MESSAGE FCBHAT SFEVIC1 EISIGK 

Generally, a screen can be divided into five areas, top to bottcm: 

1. Primary output area, ccntains general, fixed information for the 
current transaction. The fields in this area should generally be 
protected. 

2. Detail input/cutput area, used to enter and/or display the more 
variable part of the transaction data. Accepted fields should be 
protected (under program control) ; fields in error can be displayed 
with high intensity and unprotected to allow for corrections. 

3. HPP error message area. In general, one line is sufficient. This 
can be the same line as 5 below. 

U. Primary input, that is, reguested action and/or transaction code for 
next input, and primary data base access information. 

5. System message field, used by IHS/VS to display system messages and 
by the terminal operator to enter commands. 

For readability, the above areas should be separated by at least one 
blank line. The above screen layout is a general one, and should be 
evaluated for eacb individual application. It is recommended to develop 
a general screen layout and set of formats to be used by incidental 
programs and programs in their initial test. 
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This can significantly reduce the number of format blocks needed and 
maintenance. In any case, installation standards should te defined for a 
multi-application ervircrment . 

£JS_Subs€t_R€stricticn 

Cur subset use of IMS/VS imposes the following major restrictions: 

1. The maximum output length of a message segment is 1388 bytes; this 
is related to our long message record length of 1500 bytes. 

2. A format is designated for one screen size. This can be later 
changed via additional MPS statements to support both screens and 
ether devices with the same set of format blocks. A 1920 character 
format can be displayed en the top part of a 2560 or 34U0 character 
display, and a 48C character format can be displayed on the top of a 
960 character display.. 

3. A segment is one physical page, which is one logical page. 

General_S ere en_Lay,ou£_Guide lines 

The following performance guidelines should be observed when making 
screen layouts: 

1. Avoid full-format operations. IMS/VS knows what format is on the 
screen. So, if the format for the current output is the same as the 
cne on the screen, IMS/VS need not retransmit all the literals and 
unused fields. 

2. Avoid unused fields, for example, undefined areas on the screen. 
Use the attribute byte Jnon-displayed) of the next field as a 
delimiter, or expand a literal with blanks. Each unused field 
causes additional control characters (5) to be transmitted across 
the line during a full-format operation. 

Note: This has to te weighed against user convenience. For 
example, cur sample customer name inguiry format does not have 
consecutive fields but it is user convenient. Also, this 
application rarely needs a new format so we are not so much 
concerned with unused fields. 

IMS/VS reguires a transaction code as the first part of an input 
message. With MFS, this transaction code can be defined as a literal. 
In dcing so, the terminal operator always enters data on a Preformatted 
screen. The initial format is retrieved with the /FCEMAT command. To 
allow for multiple transaction codes on one format, part of the 
transaction code can b€ defined as a literal in the MID. The rest of 
the transaction code can then be entered via a DFID. This method is 
very cenvenient for the terminal operator because the actual transaction 
codes are not of his ccrcern. An example of such a procedure is shown 
in our sample customer order entry application. 
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DESIGN OF A SAMPLE INQUIRY TRANSACTION 

The sample inquiry transaction we vill consider in the following is the 
customer name inquiry, TE4CKIKC- It is a very simple transaction. 
Upon entry of the customer number, the program should retrieve the 
customer name and address and display it. If the customer number is net 
found in the data base, an error message should be sent. The design 
decisions are straightforward: 

• Non-conversational. There is no need to correlate two successive 
interactions. In case cf error, just enter a new customer number. 

• The transaction can be defined as non-recoverable inquiry-only, 
because logging is not required. In case of system failure, the 
lost input or output is not important. 

• One format can be used for both input and output. The output fields 
are protected. However, the customer number input field shculd net 
be protected, because it is to be used to enter another customer 
number. The transaction code is defined as a literal in the MIP, 
thus avoiding the reed for re-entering it each time that input is 
submitted. Switching tc another application can be easily dene by 
requesting another format via the system message field, the bottom 
line in our subset. 

The formats cf this sample are included as member OF4CNI01 in 
IMSVS.PBIMBSRC. Trey can be generated with job //SAMFU25 in 
IMSVS..PRIHEJCE. The programs, FE^CNINC. for COEOL and PEUPNINQ for 
PL/I are provided in IMS\IS.PF.ISESRC and can be compiled with jobs 
//SAMPUU1 and //SAM451 in IMSVS. PRIMEJGE, respectively. The remote 
terminal operator instructions can be found in the IKS^VS Erimer 
Remote Terminal Operators Guide, Chapter 5. 

DESIGN OF A SAMPI2 UPDATE TFAKSACTICN 

The sample update transaction chosen for this discussion is the entry of 
new customer orders, TE4CCKEW. There are two categories of data tc be 
entered when adding a new customer crder to the data base: 

• Header information, such as customer number and customer order 
number. 

• retail information for each crder line: The part number, part 
quantity, etc. 

The data base processing of the program involves: 

• Retrieval of the customer name and address for terminal operator 
verification and printirg en a packing slip (optional) . 

• Insertion of the customer order root segment. 

• For each order line, retrieval of the requested part segment and its 
associated stock segirert fcr verification. 

• Insertion of the crder line segment and update of the stock 
information fcr that part. 

The output sent to the terminal is the order confirmation and/or error 
messages. The error message can range from "customer unknown" tc "net 
enough parts in stock". Alsc, upon request, a packing slip is printed 
on a 327C terminal printer. 
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This transaction can be implemented in mary ways. He will discuss first 
the most disticctive alternatives and then cur choice. 

With this alternative, the header and all detail lines are entered at 
the same time. If everything is correct, the program inserts the 
complete customer order and displays it en the terminal. In case of 
errors, the whole order must be re-entered if it is a non-ccnversational 
transaction. If ccrversaticnal, the SPA can be used to store the 
correct order items and the necessary data base status information, to 
allcw fcr convenient terminal operator corrections. 

4lJte r na t i we _ 2 x _ T wo rlass_ Upd at e 

With this alternative, the input and data base are checked in the first 
pass; no data base updates are done. She order is stored in the SPA. 
The seebnd pass is a confirmation of the terminal operator that he 
accepts the proposed data base update. Next, the actual data base 
update is done. Wi-th this approach, most errors will be detected before 
any data base updates are done. However, the number of data base 
accesses is higher than with alternative 1. 

Also, all checking must be done again in the second phase, because the 
data base contents Bay have been chan$ed in the meantime by another 
transacticn- 

Alternative 3, Kulti-Pass Update 

With this alternative, the crder entry is done with multiple passes. 
The first pass checks and inserts the header information. Each 
successive pass checks and inserts one order line. This is a rather 
costly approach. Also, it is generally cumbersome for the terminal 
operator because he must wait for response after each order line is 
entered. This approach should enly be used for very complex 
transactions with significant operator "think-time". Remember, alsc, 
that typically the error rate in predetermined transactions is quite low 
(< 1 05t> - So the normal operator procedures should be as smooth as 
possible. On the ether hand, the error correction procedure could very 
well limit itself to one correction at a time, since the change on 
multiple errors is typically very low (<1*fr. 

ii!!A£ll.-££§_i c . -Choose 

It is clear that alternative 1 should be the first choice from a system 
performance pcint of view. If the amount of data entered is 
significant, an SPA can be used to avoid the re-entering of all input 
data in case of errcrs. The correct part of the input could be kept i 
the SPA and should be displayed on the screen with a protected field. 
If there are errors, the field in error should be displayed with 
high-intensity and the cursor should be positioned on the first field to 
be corrected. 

The basic principle behind this is: 

"Do as much as you can immediately. •• 

In our sample customer crder entry program, we made a compromise- We 
selected alternative 3 tut entering of the detail lines is in one pass. 
One reason for this is that we want to show a more elaborate use of the 
SPA. Remember that in a straightforward use of alternative 1, the SPA 
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is only used in case of errors. Another reason is that we want to be 
able to enter the next order using the sane screen format as used for 
the display cf the last order. Sith the amount of data for the full 
order, this «ould require in any case an extra operator action tc erase 
all unprotected fields. 

Cur_Samp.l5_Ccnversatici3al_Prcjgraffl 

This program, DFSMCNEW in USSVS.FHIMESHC (renamed to PEUCOBDE during 
linkage editing) has two basic passes: 

1. The initial input is the customer number and the customer order 
number. The customer name is retrieved and stored in the SEA. The 
customer order root segment is inserted and the output, including 
customer name and address, is displayed. 

2. The second input is all the orderlines. The order .lines are 
processed completely (that is, checking, stock update and order lire 
segment insert), one at a time. 

In case of error, pass 2 is repeated until all detail lines are 
correct. Already processed order lines are maintained. The SPA is 
used for keeping track cf the status. In case the insert of an 
order line fails, the stock update is reversed. Bemember, in case 
of abend, IMS/VS will tackcut all data base changes of only the 
current pass. 

Optionally, a packing slip is produced- The following MFS 
considerations apply: 

• The same format is used for both passes, bcth input and output, thus 
avoiding full screen formatting. 

• The screen layout is such that upon completion of an order, the 
heading data for the next order (customer number and customer order 
number) can be entered on the very same screen; the cursor is 
already in place. 

Miscellaneous Design Considerations 

The following design considerations should alsc be noted: 

-• The conversation will be terminated (insert blank transaction code 
in SPA) after each successful order entry. This is transparent to 
the terminal operator, because the output format is linked to a MID 
which contains the transaction code, so the operator need not 
re-enter it. 

•• Each output message should contain all the data (except the 

MCE-defined literals) tc be displayed. Yon should never rely on 
already existing data on the screen, because a clear or (re) start 
operation nay have destroyed it. 

ONLINE EATA EASE EESIGN 

The transaction/data element approach for data base design as introduced 
in Chapter 2 is fully applicable to the IMS/VS online environment. «e 
will not repeat it here but will extend it %ith some additional 
guidelines. 
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Osing secondary indexing can significantly increase the accessibility of 

online data bases. Therefore, a wider use of this facility is likely in 

the online data base design. However, its use in our subset is limited 

to the creation of additional non-root key access paths to the data base 
record. 

P£j||€E5fali-HiJ-.Ji5SJ§_Qr3ani2aticn 

Even more than for batch operations, the preferable data base 
organization for online data base operations is HBAM. HIDAM should be 
considered only if the online processing requirement is low and the 
requirement for key sequential batch processing is high. 

Remember that a secondary index can be used for incidental key 
sequential access such as needed for generic search (search with a 
partial key) - 

IiaiiSiiS£ 2l inline SHISAB Osage 

IMS/VS will schedule any application programs with a delete or insert 
(PRCCCPT=I, D, or A), against a SHISAM data base with the exclusive 
intent option. This implies, for instance, that if a BBE is delete or 
insert sensitive to a SEISAM data base, no KPP will be scheduled that 
references that SHISAM data base in its PSB. 

Dsing_an_InterB6diat€_.Data_Base 

In some applications it may be necessary to use an intermediate data 
base. Such a data base is used to store online transactions for later 
batch processing. The transaction processing is split in two phases: 

1. The online part, in which the transaction is checked and verified 
using the online data bases. Accepted transactions are stored in an 
intermediate data base. 

2. The batch part, in which the transactions in the intermediate data 
base are further processed via a batch program or BMP. 

The main reason for this approach is generally the access requirements 
to non-EL/I files. Remember, GSAM is not available in MEP regions. 

He recommend a simple structure for such an intermediate data base. The 
most straightforward implementation would be a root-only HDAM data base 
with a simple numeric rcct key, ranging between 1 and N (N=number of 
maximum expected transactions). In this situation, a simple linear 
randomizing module such as sample module DFSOALIN in IBSVS. EFIMESRC can 
be used. It would be more efficient to load the intermediate data base, 
periodically, with "empty" segments. A GHU ♦ REPL call can then be used 
instead of an ISRT call. 

There is one common problem with intermediate data bases and that is: 
"How does the HFP know what the next -to-be-used-root-key is?" The 
simplest solution is to have the latest used root key value in the first 
root segment of the data base. This value must then be updated by the 
MFP at the end of transaction processing, before a new GO" to the message 
queue. 
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CHAFTEE 4. EATA EASE PROCESSING 



STEOCTOBE OF THIS CHAPSER 

This chapter is divided intc twc major sections -- Data Ease Processing 
and Data Ccmmunication Application Programming- Both sections apply tc 
the IMS/VS DE/DC user. If ycu are a DB-cnly user, however, you may skip 
the seccnd section. 

The section covering Data Ease Processing is further divided into four 
parts. The first part deals with a general introduction to DL/I data 
base processing. It defines the basic structure of a DL/I application 
program. The second part introduces basic DL/I calls against a single 
hierarchical data base structure. It therefore uses the phase 1 sairple 
environment. It also gives guidelines and samples for Assembler, COBOL/ 
and PL/I application programs. However, the visualization of each EL/I 
call in particular is done following the CCEOL syntax. The third part 
covers the processing cf logical data bases which are implemented with 
the DL/I logical relationships. function. The fourth part deals with the 
use of secondary indexes. 

In general, data case processing is transaction oriented. You should 
refer tc "Concepts of Eata Ease Design" in Chapter 2, "Data Base 
Design," for a more detailed discussion of transactions and data bases-. 
Generally, an application program accesses one or more data base records 
for each transaction it processes. There are two basic types of Dl/I 
applicaticn programs: 

• The direct access prograir 

• The seguential access prcgrao 

A direct access program accesses, for every input transaction, some 
segments in one or more data base records. These accesses are based on 
data base record and segment identification. This identification is 
essentially derived from the transaction input. Normally it is the 
root-key value and additional (key) field values of dependent segments. 
For more complex transacticns, segments could be accessed in several 
DL/I data bases concurrently. 

A seguential applicaticn program accesses seguentially selected segments 
cf all or a consecutive sutset of a particular data base. The sequence 
is usually determined by the key of the root-segment. A seguential 
program can also access other data bases, but those accesses are direct, 
unless the root-keys of both data bases are the same. Host seguential 
application programs are report programs, which list some part of the 
data base. For such programs, ycu should consider PL/I, the report 
feature of COBOL, or the more extended facilities of GIS/VS. 

A EL/I applicaticn program normally processes only particular segments 
of the EL/I data cases. Ihe pcrticn that a given program processes is 
called an application data structure. This application data structure 
is defined~in~the~irogram specification blcck (PSE) . There is one PSB 
defined for each applicaticn program. An application data structure 
always consists cf one or mere hierarchical data structures, each of 
which is derived from a DL/I physical or logical data base- 
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LANGUAGE AND COMPILATION 

Application programs are written in one of three languages: PI/I, COBOL, 
or Assembler Language. The program is compiled through the 
user-selected language compiler and is placed in the appropriate program 
library, after it is link-edited with the DL/I language interface 
module. In our subset ve will only consider ANS COBOL with the CS ANS 
Version 4 or the CS/VS CCEC1 compilers or the PL/I optimizer compiler. 

INTEBFACE COMPONENTS 

A DL/I batch application program executes in a manner similar to any 
other OS/VS job in a region/partition- It executes, however, under the 
control of EL/I. Tc perfcrn the data base accesses as required by the 
application program, EI/I uses its own processing modules which in turn 
invoice OS/VS services. Also DL/I relies on the defined DBD and ESE 
control blocks to determine the data base organization and the program's 
access characteristics. Figure 4-1 presents an overview of Cl/I and the 
applicaticn pxcgram during execution. 
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Figure 4-1. EL/I Interface with an Application Program 

Before you execute an applicaticn program, a j3r.0gr.am sjaecif ication block 
SSJ3SISii2£ (PSEGEN) must be performed to create the p,rogram 
specification block (PSB) for the program. The PSB contains one PCE for 
each DL/I data base (logical or physical) the application program will 
access. The FCEs specify which segments the program will use and the 
kind of access (retrieve, update, insert, delete) the program is 
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authorized to. The ESEs are maintained in an IMS/VS system library 
(IMSVS.PSELIE) . The ceding and generation cf PSBs is described in 
Chapter 2, "Data Ease resign," of this manual. 

During initialization, both the application program and its associated 
PSE are loaded from their respective libraries by the IMS/VS batch 
system- The DL/I modules, which reside together with the application 
program in one partition/region, interpret and execute data base CALL 
requests issued by the program. 

The application program interfaces with DL/I via the following program 
elements: 

An ENTFY statement specifying the FCBs utilized by the program, 

A PCE-tfask which corresponds to the information maintained in the 
pre-censtructed PCE and which receives return information from DL/I, 

An I/O area for passing data segments to and from the data bases, 

Calls to EL/I specifyirg processing functions, 

A termination statement. 

The PCB mask(s) and I/O areas are described in the program* s data 
declaration portion. Program entry, calls to DL/I, processing, and 
program termination are described in the program's procedural portion. 
Calls to DL/I, processing statements, and program termination may 
reference PCE mask (s) ahd/cr I/O areas. In addition, DL/I may reference 
these data areas. Figure 1-2 illustrates how these elements are 
functionally structured in a program and how they relate to DL/I- The 
elements are discussed in the text that follows. 
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Figure 4-2. Structure of a Eatch Application Program 



IUJtIX_to_A£Elicaticn_Program 

Fef erring to Figure 4-2, when the operating system gives control to the 
EL/I control facility, the DL/I control program in turn passes control 
tc the application program (through the entry point as defined telow). 
At entry, all the PCB-names used by the application program are 
specified- The order of the ECE-names in the entry statement must be the 
same as in the PSB for this application program. The seguence of PCEs 
in the linkage section or declaration portion of the application program 
need not ke the same as the seguence in the entry statement. 

No t e s : 

1. Eatch DL/I programs cannot be passed parameter information via the 
PABM field from the EXEC statement. 
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2. Programs that operate as OS/VS subtasks of an application program 
called fcy IMS/VS Bust net issue DL/I calls. If they do, the results 
will be unpredictable. 

PCB^Mask 

A mask cr skeleton data base FCE must be provided in the application 
program. The program views a hierarchical data structure via this mask. 
Cne PCB is required for each data structure. The details are shewn in 
figure 4-3. 

As the PCB does not actually reside in the application program, care 
rust be taken to define the PCE-mask as an Assembler dsect, a COBOL 
linkage section entry, or a PL/I based variable. 

The data base PCE provides specific areas used by DL/I to inform the 
applicaticn program of the results of its calls- At execution time, all 
PCB entries are ccntrclled ty DL/I. Access to the PCB entries by the 
application program is for read-only purposes. 
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Figure 4-3. Application Program lata Ease FCB Mask 
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The following items comprise a PCB for a hierarchical data structure 
frcm a data base. 

1. Name of the ECE -- This is the name of the area which refers to the 
entire structure cf PCB fields. It is used in program statements. 
This name is not a field in the PCB. It is the 01 level name in the 
COEOL mask in figure 4-3. 

2. Name of Data Base -- This is the first field in the PCB and provides 
the DED name from the library of data base descriptions associated 
with a particular data base. It contains character data and is 
eight bytes long. 

3. Segment Hierarchy level Indicator -- DL/I uses this area to identify 
the level cumber cf the last segment encountered which satisfied a 
level of the call. When a retrieve is successfully completed, the 
level number cf the retrieved segment is placed here. If the 
retrieve is unsuccessful, the level number returned is that of the 
last segment that satisfied the search criteria along the path from 
the root (the root segment level being * 01 1 ) to the desired segment. 
If the call is completely unsatisfied, the level returned is '00*. 
This field contains character data; it is two bytes long and is a 
right- justified numeric value. 

4. DL/I Status Code -- ft status code indicating the results cf the DL/I 
call is placed in this field and remains here until another DL/I 
call uses this PCB. This field contains two bytes of character 
data. When a successful call is executed, DL/I sets this field to 
blanks cr to an informative status indication. DL/I status codes 
are summarized for quick reference in Appendix A, and described in 
detail in Appendix E. 

5. DL/I Processing Cpticr.s -- This area contains a character code which 
tells DL/I the "processing intent" of the program against this data 
base (that is, the kinds of calls that may be used by the program 
for processing data in this data base) . This field is four bytes 
lcng. It is left-justified. It does not change from call to call. 
It gives the default value coded in the PCB FBOCOPT parameter (see 
Chapter 2) , although this value may be different for each segment. 
DL/I will not allow the application to change this field, nor any 
other field in the PCB. 

6. Reserved Area for DL/I — DL/I uses this area for its own internal 
linkage related to an application program. This field is one 
fullword (4 bytes), binary. 

7. Segment Name Feedback Area — DL/I fills this area with the name of 
the last segment encountered which satisfied a level of the call. 
When a retrieve call is successful, the name of the retrieved 
segment is placed here. If a retrieve is unsuccessful, the name 
returned is that cf the last segment, along the path to the desired 
segment, that satisfied the search criteria. This field contains 
eight bytes of character data. This field may be useful in GN 
calls. If the status code is • AI» (data management cpen errcr) , the 
DD name of the related data set is returned in this area. 

8. Length of Key Feedback Area — This entry specifies the current 
active length of the key feedback area described belo.y. This field 
is one fullword {4 bytes) , binary- 

9. Number of Sensitive Segments -- This entry specifies the number of 
segment types in the data base to which the application program is 
sensitive. This would represent a count of the number of segments 
in the logical data structure viewed through this PCBt This field 
is cue fullword (4 bytes) , binary. 
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10. Key Feedback Area — DL/I places in this area the concatenated key 
of the last segment encountered which satisfied a level of the call. 
When a retrieve is successful, tfie key of the requested segment and 
the key field of each segment along the path to the reguest€d 
segment are concatenated and placed in this area. The key fields 
are positioned from left to right, beginning with the root segment 
key and following the hierarchical path. Khen a retrieve is 
unsuccessful, the keys of all segments along the path to the 
requested segment, for which the search was successful, are placed 
in this area. Segments without sequence fields are not represented 
in this area. 

Ncte: This area is never cleared, so it should not be used after a 
completely unsuccessful call. It will contain information from a 
previous call. See Figure 2-5 for an explanation of concatenated 
keys. 

Calls_To_EL/I 

Actual processing cf IHS/VS data bases is accomplished using a set of 
input/output functional call requests. 

A call request is compesed cf a CALL statement with an argument list. 
The argument list specifies the processing function to be performed, the 
hierarchic path to the segment to be accessed, and the segment 
occurrence of that segment. One segment or multiple segments along tht 
hierarchical path of segments may be operated upon with a single DL/I 
call. However, a single call never will return more than one occurrence 
of one segment type. 

The arguments contained within any DL/I call reguest include: 

For PL/I, a field containing the number of call arguments in the 
statement, exluding itself 

The input/output/ function to be performed 

The PCB name 

The segment input/cutput work area 

The identification of the data segment (s) to be operated upon. 

Follcwing is a sample cf a basic CALL statement for COBOL: 

f " --■!•- «.-- — -. .--.. — --.- ^ 

| CALL •CBLTDLI 1 CSING function, PCE-name, I/OArea, SSA 1, ..., SSAn- ! 
t- ..--..-...-.-.-.-.-..--...---.--..-..-------.---------------- -----j 

function 

identifies the DL/I functicn tc be performed. This argument is the 
name of a four-character field which describes the desired I/O 
operation. The DL/I functions are described briefly below, and in 
full detail later in this chapter. 

PCB-»name 

is the name of a data base Program Communication Block (tfCE) . See 
the section "PCE-name Argument" below. 

I/OArea 

is the name of an I/O wcrk area. See the section "I/O Work Area 
Argument" below. 
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SSA1 through SSAn 

are the names cf Segment Search Arguments, and these are optional. 
There can be a maximum of 1 SSA per level along the hierarchic path 
being accessed. See the section "Segment Search Arguments'* fcelcv,. 

IfiH£tion_Jraum6jnt: The I/O functions specified in the "function" 
argument cf the CALL statement request data services of DL/I. The 
functions provide a full data processing repertoire of retrieving, 
updating, adding, and deleting data. 

Following are the basic DL/I call functions to reguest DL/I data base 
services* 

Meaning DL^I^Call^ Function 

GET CNIQOE •GObb* 

GIT NEXT »GNbb« 

GET HCLD DNICOF •GHOb" 

GET HOLD NEXT »GHNb» 

INSEBI ■ISBT* 

DELETE 'DIET* 

EEFIACE •BEEL» 

Note: b stands for blank; each CALL function is always U characters. 

The above calls constitute four categories of segment access: 

• Betrieve a segment: GU, GN, GHO, GHN 

• Beplace a segment: BEPL 

• Delete a segment: DLET 

• Insert a segment: ISBT 

In addition to the above data base calls, there are the system service 
calls. These are used for requesting systems services such as 
checkpoint/restart* All of the above calls and some basic system service 
calls will be discussed in detail in the following sections. 

£QlrJQ§iB§-il3i3S§S i J "PCB-name" is the second (third in PI/I) argument in 
the CALL statement. It is the name of the PCB within the PSB that 
identifies for DL/I which specific hierarchical data structure the 
applicaticn program wishes tc process. 

I^O_Wo r,k_ A rea_ Argument: The I/O work area name is the third (fourth- in 
PL/I) argument in the CALL statement. The work area is an area in the 
applicaticn program into which DL/I puts a requested segment, or frcm 
which DL/I takes a designated segment. If a common area is used to 
process multiple Dl/I calls, it must be as long as the longest path cf 
segments to be processed. The work area name points to the leftmost 
byte of the area. Segment data is always left- justified within a work 
area. 

When inserting or retrieving a hierarchical path of segments with one 
call, the I/O work area must be large enough to hold the longest 
concatenation cf segments to be retrieved or inserted. 

Note: It is a good practice to make the length of a general IOABEA 
large enough tc accommodate future segment extensions. An installation 
standard could be set fcr this. 
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Segment_Search_ Arguments: For each segment accessed in a hierarchical 
path, one SSA can be provided. The purpose of the SSA is to identify by 
segment name and, optionally, by a field value, the segment to be 
accessed. 

The basic function of the SSA permits the application program tc apply 
three different kinds cf legic tc a call: 

• Narrow the field of search to a particular segment type, or to a 
particular segment-occurrence 

• Bequest that either one segment or a path cf segments be processed 

• Alter DL/I's position in the data base for a subseguent call 

Segment Search Argument (SSA) names represent the fourth (fifth for 
PL/I) through last arguments (SSA1 through SSAn) in the call statement. 
There can be or 1 SSA per level, and, since DL/I permits a maximum of 
15 levels per data base, a call may contain from to 15 SSA names. In 
our subset, an SSA consist cf cne, two or three elements: The segment 
name, command code (s) and a qualification statement, as shewn in the 
following diagram: 



i 

| SEGMENT | COMMAND | QUALIFICATION STATEMENT (QS) 

| NAME | CODE | 

| | |Begin CS|Field Name|E.O. \ Value | End QS 



| 8 bytes ! variable | 1 | 8 | 2 |1 - 255| 1 



where: 



SEGMENT NAME 

The segment cane must be eight bytes long, left- justified with 
trailing blanks as required. This is the name of the segment 
as defined in a physical and/or logical DBD referenced in the 
PCB for this application program. 

COMMAND CODES 

The command cedes are optional. They provide functional 
variations to be applied to the call for that segment type. An 
asterisk (*) follcwing the segment name indicates the presence 
of one or more command codes. A blank or a left parenthesis is 
the ending delimiter fcr command codes. Elank is used when no 
qualification statement exists. 

QUALIFICATION STATEMENT 

The presence cf a gualification statement is indicated by a 
left parenthesis fcllcwing the segment name or, if present, 
command codes. The qualification statement consists of a field 
name, a relaticnal-operatcr, and a comparative-value. 

Begin Qualification Character 

The left parenthesis, ( , indicates the beginning of a 
qualification statement- If the SSA is unqualified, the 
eight-byte segment name oi, if used, the cemmand codes, should 
be followed by a blank. 

Field Name 

is the name cf a field which appears in the description of the 
specified segment type in the EED- The name is up to eight 
characters long, left- justified with trailing blanks as 
required. The named field may be either the key field 
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(preferably) cr another data field within a segment. The field 
name is used for searching the data base, and must have been 
defined in the physical DBD. 

fiO = Eelational Operator 

is a set of two characters which express the manner in which 
the contents cf the field, referred to by the field name, is to 
be tested against the comparative-value, 

Cjaejatgr. USSUiUS 

b= or EC mu-t be equal to 

>= or GE must be greater than or egual to 

<= or LE must be less than or egual to 

b> or GT must be greater than 

b< or LT must be less than 

- or NE must be not equal to 

Note: As used above, the lowercase b represents a blank 
character- 
Comparative- value 

is the value against which the contents of the field, referred 
to by the field name, is to be tested. The length of this 
field must be egual to the length of the named field in the 
segment of the data base. That is, it includes leading or 
trailing blanks (for alphameric) or zeros (usually needed for 
numeric fields) as reguired. A collating sequence, not an 
arithmetic, compare is performed. 

End Qualification Character 

The right parenthesis, ")" , indicates the end of the 
qualification statement. 

Qualification 

Just as calls are "qualified n by the presence of an SSA, SSAs are 
categorized as either "qualified" or "unqualified ," depending on the 
presence cr absence of a qualification statement. Command codes may be 
included in or emitted frcm either qualified or unqualified SSAs. 

In its simplest form, the SSA is unqualified and consists only of the 
r.ane cf a specific segment type as defined in the Data Base Description 
(DBE) . In this form, the SSA provides Dl/I with enough information to 
define the segment type desired by the call. 

Example: SEGNAKEhb last character blank to unqualify 

Qualified SSAs (optional) contain a qualification statement composed of 
three parts: A field name defined in the DBD, a relational operator, and 
a comparative value.. DI/I uses the information in the qualification 
statement to test the value cf the segments key or data fields within 
the data base, and thus to determine whether the segment meets the 
user's specifications. Using this approach, DL/I performs the data base 
segment searching. The program need process only those segments which 
precisely meet seme legical criteria. 

Example: SEGNAMEb (FIELDXXX>=value) 
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The qualification statement test is terminated either when the test is 
satisfied by an occurrence of the segment type, or when it is determined 
that the request cannot be satisfied. 

Command Codes 

Eoth unqualified and qualified SSAs may contain one or more optional 
command codes which specify functional variations applicable to the call 
function or the segment qualification. The command codes are discussed 
in detail later in this chapter. 

General Characteristics of segment search arguments 

• An SSA may consist of the segment name only (unqualified) . It may 
optionally also include cne or more ccmmand codes and a 
qualification statement. 

• SSAs following the first SSA must proceed down a hierarchical path. 
Not all SSAs in the hierarchical path need be specified. That is, 
there may be missing levels in the path. DL/I will provide, 
internally, SSAs for missing levels according to the rules given 
later in this chapter. However, it is strongly recommended to 
always include SSAs for every segment level. 

Examples of SSAs will be given with the sample calls at each DI/I call 
discussion in the following section. 

Ie£fiiUJtion 

At the end of processing of the application program, control must be 
returned to the DL/I control program. 

C0E01 PI^I Assembler 

GCBACK. BETOEN; EETUBN ( 14, 12) , EC^O 

Warning: Since Dl/I links to your application program, return to DL/I 
causes storage occupied by ycur program to be released. Therefore you 
should close all non-DL/I data sets for CCBCL and Assembler before 
return, to prevent abnormal termination during close processing by 
CS/VS. PL/I automatically causes all files to be closed upon return. 

STATUS CODE HANELING 

After each DL/I call, a two-byte status code is returned in the PCB 
which is used for that call. We distinguish between three categories cf 
status codes: 

• The blank status code, indicating a successful call 

• Exceptional conditions and warning status codes, that is, valid 
status codes from an application point cf view 

• Error status codes, specifying an error condition in the application 
program and/or EL/I, 

The grouping of status cedes in the above categories is somewhat 
installation dependent. We will, however, give a basic recommendation 
after each specific call function discussion. It is also recommended 
that you use a standard procedure for status code checking and the 
handling of error status codes- The first two categories should be 
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handled by th€ application program after each single call. Figure 4-4 
gives an example. 



r ---- - - - - - - ---, 

\ CALL 'CBLTDLI 1 USING ..... | 

| IF PCE-STATUS EQ »GE» PERFORM PRINT-NCT-FCUND- I 

I IF FCB-STATUS NE »bb • FEBFOEM STATUS-ERROR. \ 

I everything okay, proceed ..... I 

i ... ••--.-..-.—----«---.--.-..-.-... -.j 

Figure 4-4. Testing Status Codes 

Notice that it is more convenient to directly test the regular 
exceptions in-line instead of branching to a status code check routine- 
In this way, ycu clearly see the processing of conditions that you wish 
to handle from an application point of view, leaving the real error 
situations to a central status code error routine. A detailed 
discussion of the error status codes and their handling will be 
presented later in this chapter. 

SAKPLE PRESENTATION OF A CALL 

DL/I calls will be introduced in the following sections. For each call 
we will give samples. These samples will be in a standard format as 
shown in figure 4-5. 



r 



77 GO-FUNC PICTURE XXXX VALUE »GUbb». 

01 SSACC1-GU-SE1PART. 

02 SSA001-EEGIN PICTURE 

02 

02 .... 

01 IOABEA PICTURE X(256). 



CALL ■CBLTDLI* USING GU-FUNC ,PCB-NAHE ,ICARE A ,SSA00 1-GU-SE 1 EABT. 



STAIUS_CgCES: 

bb: successful call 

— : exceptional but correct condition 
other: error situation 

i--« _. — —-—-------.----------- — .----,----.-.-----,. .-.-.«j 

Figure 4-5. Sample Call Presentation 

All the calls in the samples are presented in CCBCL format. The coding 
of a call in PI/I or Assembler will be presented later. Each call 
example contains three sections. The first section presents the 
essential elements of working storage as needed for the call. The 
second part, the processing section, contains the call itself. Note 
that the PCB-NAME parameter should refer to the selected PCE defined in 
the Linkage Section. Sometimes we will add some processing function 
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description before and/or after the call r in order to show the call in 
its right context. The third section contains the status codes and 
their interpretation, which can be expected after the call- The last 
category of status code, labeled "other: error situation," would 
normally te handled by a status code errcr routine- We will discuss 
these error status codes with the presentation of such a routine later 
in this chapter. 

BASIC_DAlA_BASE_!l<gCES£I!JG 

DL/I POSITIONING CONCEPT 

To satify a call, DL/I relies on two sources of segment identification: 

• The established position in the data base as set by the previous 
call against the FCE 

• The segment search arguments as provided with the call. 

The data base position is the knowledge of DL/I of the location of the 
last segment retrieved and all segments above it in the hierarchy. This 
position is maintained by DL/I as an extension of, and reflected in, the 
PCB. When an application program has multiple PCBs for a single data 
base, these positions are maintained independently. For each FCE, the 
position is represented by the concatenated key of the hierarchical path 
from the root segment down tc the lewest level segment accessed- It 
also includes the positions of non-keyed segments. 

If no current position exists in the data base, then the assumed current 
position is the start cf the data base. This is the first physical data 
base record in the data base. With HDAM this is not necessarily the 
root-segment with the lewest key value. 

SAMPLE ENVIRONMENT 

The phase 1 sample environment is used to exemplify the basic DI/I calls 
presented in the following sections. The data base used is the PARTS 
data base as shown in Figure 4-6. 
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Figure 4-6. The Ehase 1 FBETS Data Base 
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The following programs are part of the IMS/VS Primer phase 1 sample 
application and are included in IMSVS. PRIMESRC: 

• BFSOAEEI, a data base lead program written in Assembler, 

• FE1CPINV (member DFS1CINV in IHSVS. PFI MESBC) , a COBOL program which 
gives a parts inventory report for some (transaction TE1INVCJ or all 
(transaction TE1INVEE) of the parts in the PARTS data base, 

• EE1CPPUB {member DFS1CPUB in IMSVS. PBIMESRC) , a COBOL program which 
processes the purchase ciders (transactions: TE1F0NEW, TF1ECCNG, 
TE1PCDEL). This program utilizes GSAM and the batch 
checkpoint/restart function of DL/I. 

For more details on these programs, you are referred to "Phase 2 Sample 
Requirements" in Chapter 2, "resigning Data Bases." 

RETRIEVING SEGMENTS 

There are two basic functions in retrieving a segment: 

• Retrieve a specific segment: GO 

• Retrieve the next segment in the hierarchy: GN 

The Get Dnigue_Call. — GC 

The basic get unique (GO) call, function code *G0bb', retrieves one 
segment in a hierarchical path. The segment retrieved is identified by 
an SSfi for each level in the hierarchical path down to and including the 
requested segment. Each should contain at least the segment name. The 
SSA for the root-segment should provide the root-key value. Figure 4-7 
shows an example of the get unique call. 

The main use of the GO call is to position yourself to a data base 
record and obtain (a path of) segment (s). Typically, the GU call is 
used only once for each data base record you wish to access. Additional 
segments within the data base record would then be retrieved by means of 
get next calls (See the following section.) The GU call can alsc be 
used for retrieving a dependent segment, by adding additional SSAs to 
the call. For example, if you add a second SSA which specifies the 
stock location, you would retrieve a STOCK segment below the identified 
part. If the SSA did net provide a stock location number, this would be 
the first STOCK segment for this part. 
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77 GU-FUNC PICTOBE XXXX VALUE •GUbb'. 

01 SSA001-GO-SE1FAET. 

02 SSA0C1-EIGIN PICTURE X ( 1 9) VALDE • SElPAETb (FE1 PGFNBb= • . 
02 SSA0C1-FE1PGENF PICTOBE X (8) . 
02 SSA001-INE PICTURE X VALUE •)'- 

01 ICAEEA PICTURE X(256). 



MOVI FARI-NUWBEB 10 SS AOO 1-FE1FGENB. 

CALL »CELTrLl» USING GU-FOHC ,ECB-NAME, ICABEA, SS AOO 1-GU-SE 1PABT- 

STATUS_COE|S: 

bt: r€guest€d PART segment has been mcved to IOAKEA 
GE: segment not found; supplied part number not in data fcas€ 
other: error situation 

i --. . , j 

Figure 4-7. Basic GO Call 

The.Get_Next_Call_-; - GN 

The get next (GN) call, function code •GNbb 1 , retrieves the next segment 
in the hierarchy as defined in the FCB. To determine this next segment, 
EL/I relies on the previously established position. 
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77 GN-FUNC FICTCBE XXXX VALUE »GNbb«. 
01 IOABEA EICTCBE X(256). 

CALL 'CELTDLI 1 USING GN-FUNC ,PCB-NAHE,ICAREA. 



STATUS.COEES: 

bb: if previous call retrieved a PART, then a STOCK segment 

will fce retrieved 
GK: a segment is returned in ICABEA, but it is a different 

type at the sajre level, fcr instance, a PURCHASE 

ORDER segment after the last stock segment 
GA: segment returned in IOAREA, but it is of a higher level 

than the last one, that is, a new PART segment 
GE: end cf data fcase reached, no segment retrieved 
ether: error situation 



Eigure 4-8. Unqualified Get Next Call 

The abeve get next call with no SSAs at all will, if repeated, return 
the segments in the data base in hierarchical sequence. Only those 
segments are returned to which the program is defined sensitive in its 
PCE. If this call was issued after the get unique call of Figure 4-7, 
then it wculd retrieve the first STCCK segment for this part (if one 
existed) . Subsequent calls wculd retrieve all other STOCK segments, 
PURCHASE ORDER, and DESCRIPTION segments fcr this part. After this, the 
next part would be retrieved and its dependent segments, etc., until the 
end of the data base is reached. Special status codes will be returned 
whenever a different segment type at the same level or a higher level is 
returned. No special status cede is returned when a different segment 
at a lower level is returned. You can check for reaching a lower level 
segment type in the segment level indicator in the PCB. Remember, only 
those segments to which the program is sensitive via its PCB are 
available to you. 

Althcugh the above unqualified GN call may be efficient, especially for 
report programs, you should use a qualified GN call whenever possible. 

The fiualified Get Next Call: This qualified GN call should at least 
identify the segment ycu want to retrieve. In doing so, you will 
achieve a greater independence toward possible data base structure 
changes in the future. If you supply only the segment name in the SSA, 
then you will retrieve all segments of that type from all data base 
records with subsequent qet next calls (see Figure 4-9). 
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77 GN-FUNC PICTURE XXXX VfilUE •GNbb 1 . 

01 SSA002-GN-SE1FPUE FICTUEE X (9) VALUE •SElPPUEtt». 

01 ICABEA PICTCEE XJ256). 

CALL •CELTELI' USING GN-FUKC,ECE-NAME, ICiBEA, SSA00 2-GN-SE1PPUE- 



§1A20S_COE|£: 

bb: next PURCHASE OBDEE segment has been moved to IOAEEA 
GB: end of data base reached, no more PURCHASE OBEER segments 
other: error situation 



Figure 4-9. Qualified Get Next Call 

Repetition of the above GN call will retrieve all subseguent FUFCHASE 
ORDER segments of the data base, until the end of the data base is 
reached. To limit this to a specific part, you could add a fully 
gualified SSA for the BAFT segment. This would be the same SSA as used 
in Figure 4-7. 

An example of a gualified get next call with a gualified SSA is shown in 
Figure 4-10. Ihis fully gualified get next call should be primarily 
used. It always clearly identifies the hierarchical path and the 
segment ycu want to retrieve. 



77 GN-FUNC PICTURE XXXX VAIUE •GNbb 1 . 

01 SSA001-GU-SE1FABI. 

02 SSA001-BIGIN PICTURE X |1S) VALUE • SElPARTb (FE 1PGFNRb= • . 

02 SSA0C1-FE1EGFNB PICTURE X(8). 

02 SSA0C1-END PICTURE X VALUE •) '- 
01 SSA002-GN-SE1PPUR PICTURE X(S) VALUE «SElPPURb«. 
01 ICAREA PICTUEE X(256). 



CALL •CBLTDLI* USING GN-FUSC, ICE-NAME, ICAREA, SSA001-GU-SE1PAP.T, 
SSA002-GN-SE1FEUR. 



STAIUS.COEES: 

bb: next PURCHASE ORDER segment is in IOAREA 
GE: segment not found; no more purchase orders for this part, 
or part number in SSAC01 does not exist 
ether: error situation 



Figure 4-10. GN Call with Qualified SSA 
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G€t_jjold_Calls 

To change the contents cf a segment in a data base through a replace or 
delete call, the program must first obtain the segment- It then changes 
the segment's contents and reguests DL/I to replace the segment in the 
data base cr to delete it from the data base- 

This is done ty using the get hold calls. These function cedes are like 
the standard get function, except the letter 'H* immediately follows the 
letter *G* in the code (that is, GHU, GHN)- The get hold calls function 
exactly as the corresponding get calls fcr the user- For DL/I they 
indicate a possible subseguent replace or delete call- 
After DL/I has provided the requested segment to the user, one or mere 
fields, but not the sequence field, in the segment may be changed. 

After the user has changed the segment contents, he can call EL/I to 
return the segment to, or delete it from the data base. If, after 
issuing a get hold call, the program determines that it is not necessary 
to change cr delete the retrieved segment, the program may proceed with 
other processing, and the "hold" will be released by the next EL/I call 
against the sane FCE. 

UPDATING SEGMENTS 

Segments can be updated by application programs and returned to DL/I for 
restoring in the data base, with the replace call, function code 'REPL 1 .. 
Two conditions must be met: 

• The segment must first be retrieved with a get hold call, GHU or 
GHN; no intervening calls are allowed referencing the same PCB. 

• The sequence field of the segment cannot be changed; this can only 
be dene with combinations of delete and insert calls for the segment 
and all its dependents. 

Figure 4-11 shows an example of a combination of a GHU and REPL call. 
Notice that the replace call must not specify a SSA for the segment to 
be replaced- If, after retrieving a segment with a get hold call, the 
program decides not to update the segment, it need not issue a replace 
call. Instead the program can proceed as if it were a normal get call. 

Because there is only a very small performance difference between the 
get' and the get hold call, you should use the get hold call whenever 
there is a reasonable chance (about 5% or more) that you will change the 
segment. 
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77 GHU-FUNC PICTURE XXXX VAIOE •GHOb» . 
77 BEPL-FUNC FICTUBE IXIX VALUE •EEPL 1 , 
01 SSA001-GU-SE1PABI. 

02 SSA001-BEGIN PICTOBE X(19) VALUE 'SElPABTb (FElPGPNBb=» . 

02 SSA001-FE1PGPNB PICTUBE X (8) . 

02 SSA0C1-FNE PICTOBE X VALUE •)*• 
01 SSA002-GN-SE1FP0B PICTOEI X (9) VALUE •SElPPUBbb* , 

01 IOABEA PICTOBE X (256) . 



MOVE PABT-NUMBEE TC SSAOO 1-FE 1FGFNB. 

CALL •CBLTBLI' OSING GH0-F0NC,PCB-NAKE,IOAREA,SSA001 -GU-SE1PABT, 
SSA002-GN-SE1FFUB. 

The retrieved P0ECHAS1 CELEB segment can now be changed by the 
progran in the IOAREA. 

CALL •CELTELI 1 OSING REPL-FONC,PCB-NAWE,ICAREA. 



STA10S_COi; JS_ Ja f t€i_BEEI_calll : 

bb: segment is replaced with contents in IOABEA 
other: error situation 

L-- --------------------------------------------- ------------ .....J 

Figure 4-11. Basic REFI Call 

DELETING SEGMENTS 

To delete the occurrence of a segment from a data base, the segment must 
first be obtained by issuing a get hold (GHC, GHN) call through EL/I. 
Once the segment has been acquired, the ELET call may be issued. 

No EL/I calls which use the ease FCB must intervene between the get hold 
call and the ELET call, or the DLET call is rejected. Quite often a 
program lay want to process a segment prior to deleting it. This is , 
permitted as long as the processing does net involve a EL/I call which 
refers to the same data base PCE used for the get hold/delete calls. 
However, other PCEs may be referred tc between the get hold and DLET 
calls. 

DL/I is advised that a segment is to be deleted when the user issues a 
call that has the function ELET. The deleticn of a parent, in effect, 
deletes all the segment occurrences beneath that parent, whether or not 
the application program is sensitive to these segments. If the segment 
being deleted is a root segment, that whole data base record is deleted. 
The segment to be deleted must still be in the IOABEA of the delete call 
(with which no SSA is used) , and its seguence field must not have been 
changed. Figure 4-12 gives an exasple of a DLET call. 
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77 GHU-EONC PIC1CBE XXXX VAIUE •GHOfc 1 . 
77 ELET-FUNC PICIUBE XXXX VALOE ■DLE1«. 
C1 SSA001-GU-SE1EABT. 

02 SSA00 1-BEGIN PICTCEE X(19) VALUE • SElPABTb (FElPGPNBb= • . 

02 SSA00 1-FE1EGENB EICTUBE X (8) . 

02 SSA001-END FICTUFE X VA1UE •)•• 
01 SSA002-GN-SE1PPUB PICTUBE X (9) VALCE •SElEPUBbb'. 

01 IOAEEA PICTUBE X(256). 



CALL 'CELTDLI' USING GHU-FUNC,PCB-NAME,IOABEA ,SSA0O 1-GU-SE1 EABT, 
SSA002-GN-SE1PPUB. 

The retrieved PURCHASE OEDEE segment can new be processed by 
the program in the ICABEA 

CALL •CBLTDLI' USING EIET-FUNC, ECB-NAHE, IOABE*. 



STATOS_COB!S_Jaft€£_PlET_cal!l: 

tb: requested purchase order segment is deleted from the data 
base; all its dependents, if any, are deleted also, 
ether: error situation 

c ..... — . ,- J 

Figure 4-12- Easic DIET Call 

INSEB1ING SEGMENTS 

Adding new segment cccurrences to a data base is done with the insert 
call, function code •ISRI 1 . 

The DL/I insert call is used for two distinct purposes: It is used 
initially to lead the segments during creation of a data base- It is 
also used to add new occurrences of an existing segment type into an 
established data base- The processing options field in the PCB 
indicates whether the data base is being added to or loaded. The format 
of the insert call is identical for either use. 

When loading or inserting, the last SSA must specify only the name cf 
the segment being inserted. It should specify only the segment name, 
not the seguence field. Thus an unqualified SSA is always required. 

Up to the level to be inserted, the SSA evaluation and positioning for 
an insert call is exactly the same as for a GU call. For the level to 
be inserted, the value of the sequence field in the segment in the user 
I/C area is used to establish the insert position. If no sequence field 
vas defined, then the segment is inserted at the end of the physical 
twin chain. If multiple ncn-unigue keys are allowed, then the segment 
is inserted after existing segments with the same key value. 

Figure 4-13 shows an example of an ISBT call. The status cedes in this 
example are applicable ccly tc ncn-initial load inserts. The status 
codes at initial load time will be discussed under the topic "Loading A 
Basic Data Ease" later in this chapter. 
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77 ISBT-FCNC FICTUBE XXXX VAIUE •ISET*. 
01 SSA001-GU-SI1PABI. 

02 SSA001-BEGIN FICTOBE X(19) VALUE 'SElPABTb (FElPGPNBt* 1 . 

02 SSA0C1-FF.1PGPNB PICTDBE X (6) . 

02 SSA0G1-END PICTOBE X VAIUE •)». 
01 SSA002-GN-SI1PPOB FICTUBE X (9) VALOE »SE1PPUBbb«. 

01 ICABIA FICTUBE X (256) . 



MOVE FABT-NUMBEB IC SSAOO 1-FE1PGFNB. 

MOVE POBCHASI-CBDEE TC ICAEEA. 

CALL •CELTELI* USING ISBT-FUNC,FCB-NAHE,ICABEA, SSAOO 1-GU-SE 1PABT, 
SSA0C2-GN-SE1PPUB. 



ST A TUS.CODE S. : 

bb: new PUBCHASE CEEEF segment is inserted in data base 

II: segment to insert already exists in data base 

GE: segment not found; the requested part number (that is, 

a parent of the segment to be inserted) is not in the 

data base 
other: error condition 



Eigure U-13. Easic ISBT Call 

Note: There is no need to check the existence of a segment in the data 
base vith a preceding retrieve call. DL/I will do that at insert time, 
and will notify you with an II cr GE status code. Checking previous 
existence is enly relevant if the segment has no sequence field* 

CALLS HUH CCMMAKE CCDES 

Eoth unqualified and qualified SSAs may contain one or more optional 
command codes vhich specif; functional variations applicable to either 
the call function or the segment qualification. Command codes in an SSA 
are alvays prefixed by an asterisk (*) , vhich immediately follows the 6 
byte segment name. Figure 4-14 illustrates this. Following are some 
important command codes. 

f-Cgmman decode 

The • £• command code is the cne mest widely used. It requests EI/I to 
issue £ath calls. A "path call" enables a hierarchical path of segments 
to be inserted or retrieved with one call. (A "path" was defined 
earlier as the hierarchical sequence of seqments, one per level, leading 
frcm a segment at one level to a particular segment at a lower level.) 
The meaning of the *D' command code is as follows: 

For retrieval calls, multiple segments in a hierarchical path will 
be moved to the I/C area with a single call. The first through the 
last segment retrieved are concatenated in the user's I/C area. 
Intermediate SSAs may be present vith or without the ' D' command 
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code. If without, these segments are not moved to the user's I/C 
area. The segment named in the PCB "segment name feedback area" is 
the lowest" level segment retrieved, cr the last level satisfied in 
the call in case of a non-found Condition. Higher-level segments 
associated with SSfts having the 'D' command code will have teen 
placed in the user's I/O area even in the not-found case. The 'D' 
is not necessary for the last SSA in the call, since the segment 
which satisfies the last level is always moved to the user's I/C 
area- A processing option of 'P' must be specified in the PSEGEN 
for any segment type fci which a command code ' D' will te used. 

For insert calls, the 'D' command code designates the first segment 
type in the path to be inserted- The SSAs for lower-level segments 
in the path need net have the D command code set, that is, the E 
command code is propagated to all specified lower level segments. 

Figure 4-14 shows an example of a path call. 



r" 



77 GU-FUNC PICTUBE XXXX VALUE 'GUbb*. 

C1 SSAC04-GCD-SElPaBT. 

02 SSA004-BEGIN PICTURE X(21) VALUE • SE 1PABTb*D (FE 1PGFKFb= • . 
02 SSACC4-FE1EGENB PICTOEE X (8) . 
02 SSA004-END PICTOEE X VALUE ')'. 

01 SSA005-GN-SE1FGDSC EICTUBE X (9) VALUE « SE 1PGDSCC' . 

01 IOABEA PICTOEE X (256) . 



CALL 'CELTELI' USING GU-FUNC, FCB-NAME, ICAEEA, 

SSA00 4-G0D-SE1PART.SSA0C5-GN-SE1FGDSC. 



ST AT US_ CODES: 

fcfc: both segments (PABT and DESCEIPTICN) have been placed 

in IOAREA 
GE: segment not found; PABT segment may be retrieved in 

IOAREA; check segment name and level indicator in PCB. 
ether: errcr condition 



Figure 4-14. Sample Path Retrieve Call 

The above example shows a common usage of the path call. Although we 
don't know if the requested part has a separate DESCRIPTION segment 
(SE1PGESC), we retrieve it at almost no additional cost if there is one. 

The correct usage of path calls can have a significant performance 
advantage. You should use it whenever possible, even if the chance of 
the existence or the need fcr the dependent segment(s) is relatively 
small- For instance, if you would need, in \0% or more of the 
occurrences, the first dependent segment after you inspect the parent, 
then it is generally advantageous to use a path call to retrieve them 
both initially. 
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lLCommajid_Cod€ 

When a replace call follows a path retrieve call, it is assumed that all 
segments previously retrieved with the path call are being replaced. If 
any of the segments have net been changed, and, therefore, need not be 
replaced, the •N* command code may be set at those levels, telling EL/I 
not to replace the segment at this level of the path. The status codes 
returned are the same as fcr a regular replace call. 

JL£2JSJ8£!Jj3_Cod€ 

This command code allows ycu tc back up to the first occurrence of a 
segment under its parent. It has meaning only for a get next call. A 
get unique call always starts with the first occurrence. Command code F 
is disregarded fcr the root segment. 

i.Q c m ma n d _Code 

This command code allows ycu to retrieve the last occurrence of a 
segment under its parent. This command code should be used whenever 
applicable. 

r.S2fiJ5SJ-C2de 

The hyphen is a null cemmand cede. Its purpose is to simplify the 
maintenance of SSAs using command codes. 

DATA BASE POSITIONING AFTEF A EI/I CALI 

As stated before, the data base position is used by DL/I to satisfy the 

next call against the PCB. She segment level, segment name and the key 

feedback areas of the ICE are used to present the data base position tc 
the application progran. 

The following basic rules apply: 

1. If a get call is completely satisfied, current position in the data 
base is reflected in the PCE key feedback area. 

2. A replace call does not change current position in the data base. 

3. Data base position after a successful insert call is immediately 
after the inserted segment. 

4. Eata base position after return of an II status code is immediately 
prior to the duplicate segment. This positioning allows the 
duplicate segment to be retrieved with a GN call. 

5. Eata base position after a successful delete call is immediately 
after all dependents of the deleted segient. If no dependents 
existed, data base position is immediately after the deleted 
segment. 

6. Data base position is unchanged by an unsuccessful delete call. 

7. After an (partial) unsuccessful retrieve call, the PCB reflects the 
lowest level segment which satisfied the call. The segment name or 
the key feed back length should be used to determine the length of 
the relevant data in the key feedback area- Contents of the key 
feedback area beyond the length value must not be used, as the 
feedback area is never cleared out after previous calls. If the 

Data Ease Processing U.23 



level-one (root) SSA cannot be satisfied, the segment name is 
cleared to blank, and the level and key feedback length are set 
to 0. 

In considering f current position in the data base* , it mast be 
remembered that DL/I must first establish a starting position to be used 
in satisfying the call. This starting position is the current position 
in the data base for get next calls, and is a unigue position normally 
established by the root SSA for get unigue calls. 

The following are clarifications of 'current position in the data base 1 
for special situations: 

• If no current position exists in the data base, then the assumed 
current position is the start of the data base. 

• If the end of the data base is encountered, then the assumed current 
position to be used by the next call is the start of the data base.. 

• If a get unigue call is unsatisfied at the root level, then the 
current position is such that the next segment retrieved would be 
the first root segment with a key value higher than the one of the 
unsuccessful call, except when end of the data base was reached (see 
above) or for HDAM, where it would be the next segment in physical 
sequence. 

You can always reestablish your data base positioning with a GO call 
specifying all the segment key values in the hierarchical path. It is 
recommended that you use a get unigue call after each not found 
condition- 

USING MULTIELE ECEs FCF CKE DATA BASE 

Whenever there is a need to maintain two or more independent positions 
in one data base, ycu should use differert PCBs. This avoids the 
reissue of get unigue calls to switch forward and backward from one data 
base record or hierarchical path to another. There are no restrictions 
as to the call functions available in these multiple PCBs. However, to 
avoid "position confusion" in the application program, you should not 
apply changes via two PCEs to the same hierarchical path. , For 
simplicity reasons you should limit the updates to one PCB unless this 
would cause additional calls. 

SYSTEM SEFVICE CALLS 

Besides call functions for manipulating data base segments, DL/I 
provides special system service calls. The most common ones are: 

• STATISTICS (STAT) — This call is used to obtain various statistics 
ficm OL/I. 

• CHECKPOINT (CHFE) -- CHFE informs EL/I that the user has 
"checkpointed" fcis program and that it thus may be restarted at this 
point. The current position is maintained in GSAM data bases. For 
all ether data bases, you must reposition yourself after each 
checkpoint call with a get unigue call. 

• RESTART (XfiST) — XRSI requests DL/I to restore checkpointed user 
areas and reposition GSAH data bases for sequential processing if a 
checkpoint ID for restarting has been supplied by the call or in the 
JCL. 
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The XES1 and CHKF calls will b€ discussed under the topic "Batch 
Checkpoint/Restart" later ir. this chapter. 

The_STAT_Call 

The STAT call retrieves the statistics information of the data base 
buffer pool (s) . A discussion of those pools and their statistics can be 
found in Chapter S; "Optimization." We will not include a detailed 
discussicn of the STAT call. Instead we provide a general subroutine, 
DFSOAST in I MSVS.ERIMESBC , which performs the STAT call, formats and 
prints the statistics. This subroutine can be called from any EL/I 
batch program- la obtain the print of the statistics you must include a 
SYSOOT card in the JCL with ddname of //DCCS1AS. If you don»t want the 
statistics, just leave out this EE statement. 

The basic format of the call statement to call this subroutine in C0B01 

is: 

r -_ ------ --------- - - -- - - t 

| CALL •DFSOAST 1 ISING pcb-name. I 

i ---- ---j 

pcb-name: can be any data base PCB in ycur program. 

No status code checking should be done after return. Typically, the 
statistics will fc€ requested at the end of each batch program. 

PROCESSING GSAM EAIA EASES 

All accessing to GSAM data bases is done via DL/I calls. A check is 
made by DL/I to determine whether a user request is for a GSAM data 
base. If so, control is passed to GSAM, which will te resident in the 
user region. If not, ccntrcl is passed tc DL/I, and standard 
hierarchical processing will result. 

Calls to be used for GSAK accessing are: 

r -- - ------------------------------------- .---.-.-..., 

| CALL •CBLTDLI 1 DSING call-f unc,pcb-name # ioarea . I 

(.-..-. -------------------------------J 

where: 

call-f unc 

is the name of the field which contains the call functicn: 

• OPEN Cpen GSAM data base 

• CLSE Clcse GSAM data base 

• GN Retrieve next sequential record 

• ISRI Insert a new logical record (at end of data 

base only) 

The open and clcse call are optional calls to be used to 
explicitly initiate or terminate data base operations. The 
data base will automatically be opened by the issuance of the 
first processing call used and automatically closed at 
"end -of -data" or at program termination. 
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Becords nay net b€ randomly added to GSAH data sets. The data 
set nay be extended by opening in the load node, vith EISE=MCE, 
and using the ISBT function code. 

• peb-nane 

is the name of the GSAH PCB 

• ioarea 

is the name of the I/O area for GN/ISBT calls, or the optional 
address of the CEEK-option for an OPEN call. The OPEN option 
is either 2NP, OUT, or, in the case of SYSOOT type data sets, 
OUTA or CCTM to include the standard print or punch control 
characters (A fcr ASA, M for Machine) • 

STATUS COEES: 

• bb: CK, proceed 

• GB: end of data (get next only) 

• other: error situation 

RECORD FORMATS: 

Becords may be fixed or variable length, blocked or unblocked. Becords 
ffust be unkeyed. The inclusion of carriage control characters may also 
be indicated in the JC1 RECFH subparameter (for example, BECFM=FBA) for 
all record fonats. The record in the ICAREA includes a halfword record 
length for variable length records. 

Sample GSAH processing is shewn in programs PE1CPPUR and PE3CPPUR 
(members EFSICPUR and DFS3CPUR, respectively) in IMSVS. PRIMESBC. 

The use of GSAH data sets in a checkpoint/restart environment is further 
discussed later in this chapter. 

LOADING A BASIC DATA BASE 

After generating the physical DBD, you can load your data base using a 
load program. Basically the lead program reads a seguential file with 
the data base record contents; it builds the segments and inserts then 
in the data base in hierarchical order. Quite often the data to be 
stored in the data base already exists in one or more files, but merge 
and sort operations may be required to present the data in the correct 
sequence. Soietimes even clean-up and correction activities are 
required, especially when multiple files with redundant data are merged 
into one data base (see Figure 4-15). 
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ERRORS 
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PROGRAM 




DBLOAD 
PROGRAM 



T 



LOAD 
REPORT 



DATA BASE 



Figure U-15. Basic Data Ease lead Process 



Sam£le_Data_Ease_!gad_irogram 

The sample data base load program EFSOAEBL in IMSVS.PRIMEJOB may te used 
to load the sample data bases. It may also be used as a general data 
base lead program to load your own data bases. Furthermore, you vill 
find this program, due to its modular structure, easy to modify should 
you vish to do so. lo use the program as it is, use the following 
guidelines: 

• The input data can be any OS/VS sequential file supported by QSAH. 
Each segment must be stored in one record vith the following format: 

Positions 1 through 3: segment code (see Figure 2-4), 2oned 
decimal, 001 is the rcot segment, laximum 255 
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Positions H to N: not used by the load program; can be used to 
store additional sequence fields for sort purposes. N is 
defined for each segment in the control input. 

Fosition N and beyond; the segment data in exactly the format 
you wish it stored in the data base- 

• The input contrcl file contains one card for each segment type to be 
leaded, with the following format: 

Eositions 1-3: segment code, 001-255 

Position 4: blank or comma 

Eositions 5-12: segment name 

Position 13: blank or comma 

Positions 1*1-17: position of first byte of input data in the 

input record; default is 0004 (this is N as 
defined for input data above) 

Positions 18-26: blanks 

Eositions 27-8C: not used 

Note: This load program does not manipulate the actual data base data; 
however, it dees provide the hecks to add such functions easily- The 
program listing should fce consulted for guidance. 

Loadins_a_jjIEAM_Eata_Bas€ 

When loading a HIDAM data base initially, you must specify EFCCCET=LS in 
the PCB. Also, the data base records must be inserted in ascending root 
key seguence, and the segments must be inserted in their hierarchical 
segue nce- 

§°.££iS9_§§95S 2i§_iS_l}i§E§f£i}ical_seauence: If there is a need to sort on 
a segment level, you must provide the following sort control fields with 
each segment (figure 4- 16) : 



r n 

| ECCI | LEVEL 2 | LEVEL 2 | LEVEL 3 | LEVEL 3 j | 

| KEY | SEGMENT | KEY | SEGMENT | KEY | etc. | 
| | COEE | ! CODE | | | 

l-. ........... ......... ...................... -.-----_-----.. -J 

Figure 4-16. Control Field for Sorting Segments into Hierarchical 
Seguence 

Notes: 

1. The level 2 segment code for the root segment should contain a lower 
value than ether level 2 segment codes. 

2. For every level, the key field length should be equal to the largest 
segment key field on that level- Shorter keys should be left 
adjusted and padded with lew value characters. 

3. Segments on the lowest level need not have a key field if no 
sequence field is defined; however, their sequence below their 
parent might be different after the sort. If no sequence field is 
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available in the segment itself, you should provide one. This cculd 
be a sinple dependent segment counter provided by the "clean up and 
format" program in Figure 4-15. 

4- The above fields must fce filled in for every segment. So a level n 
segment has the segment code of its superior segment at phase 2 
[that is, the phase 2 segment it is a dependent of) stored in the 
"phase 2 segment cede" ccntrol field, and so forth. 

5. When using the sample data base load program (DFSOADBI), the above 
sort control field, can be within the same input record as the 
segment itself. 

When leading the HIDAM data base, DL/I will also load the primary index 
data base, lou must, however, provide a BE statement for the data space 
of this primary index with ycur jcb. Job //SAMP270 in IMSVS..PBIKEJCE 
can be used to load our sample phase 2 customer order BIDAH data base. 

Mote: When loading a HIDAE data base, EL/I will automatically insert a 
high key (X*Ff«..') at the end cf the data base. This is for its chain 
maintenance, it is completely transparent fcr your program. But you 
shculd net use this kej in your application. 

l2§£AM_§-S2AH_Data_Base 

When initially loading a HEAD data base, you should specify PBOCOPT-l in 
the FCE. There is no need for Dl/I to insert the data base records in 
roct key order, but you must still insert the segments in their 
hierarchical order. Fcr performance reasons it is advantageous to sort 
the data base records into physical sequence. The physical sequence 
should be the ascending seguence of the blcck and root anchor point 
values as generated by the randomizing algorithms. This can be achieved 
by an E6 1 type scrt exit rcutine, which gives each root key to the 
randomizing module for address conversion, and then directs SOFT tc sort 
on the generated address + rcot key value. Such a general exit routine 
is F^cvided as sample EFSOASRI in IMSVS.PRIMESBC. 

Job //SAMP170 in IMSVS.FFIKE JCE shows the JCL to load the phase 1 HEAM 

parts data base. Nodule BFSOASBT is used, as an £61 sort exit routine, 

to sort the segments in the desired seguence, and program EFS0AEE1 is 
used for the actual load. 

!2§i|ing_a_SHISA!LEata_JEase 

Loading a SHISAM data base is the same as loading a root only HIDAM data 
base. Just insert the roct segments in ascending key sequence. No 
sample is provided for this because the SHISAM data base was created as 
a KSES. 

Statu§_Codes - fpr_.Eata_Ease_Lcadii}jg 

The following status cedes can be expected when loading basic data bases 
after the ISBT call: 

bb: CK, segment is inserted in data base 

LE: the segment ycu tried to insert already exists in the data 
base 

1C: key field of segment is out of sequence 
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LD: no parent has been inserted for this segment in the data 
base. 

other: error situation 

STATUS CODE EBBCB BCUTISE 

There are essentially twc categories of error status codes: those caused 
by application program errors and those caused by system errors. 
Sometimes, however, a clear split cannot be made immediately. Appendix 
E contains a listing of the status cedes in both of these categories, 
together with an explanation and suggested actions. 

This listing is not complete, but does contain all the status codes you 
should expect using our subset of OL/I. You should refer to Appendix E 
of the "IMS/VS Application Programming Reference Manual," if you should 
need a complete listing cf all possible status codes. 

To aid the debugging of programs SSAs, a status code error routine 
should print critical system information like CALLID, IOAREA, PCB, etc. 
The sample error status cede routine, DFSOAEE, in IMSVS. PRIBESRC 
provides such services. To call this routine from your application 
program code (COEOL): 

r -----.-- ...... ---.-. -- ............... --"t 

ICALL •DFSOAEB 1 USING peb-name, call-label, areal, options, area2,.. . area9 | 
i................. ....................................... ---------....j 



where: 



peb-name 

name of PCB used for the preceding DL/I call 

call-label 

name of symbolic label identifier of the preceding DI/I call. 
Eeguired format: Exxxxxxx, when using a DE PCB; Cxxxxxxx, when 
using a DC PCB. 

options 

address of a 4 byte option field. 

tyte 1: CM' Abnormal termination after print; 

recommended for production. 
CO 1 Return to caller after print. This enables 
multiple invocations for testing purposes. 
A final invocation is required. 

C'2 1 Final invocation to close print data set, 
program gets control back. 

C'2' Message DFS3125A will be issued. This is 
used by the sample programs for testing 
recovery procedures. See the IMS/VS 
Messages and Codes Reference Manual for 
more details. 

byte 2,3,4: reserved 

area 1, ...area9 

program areas to be printed by DFSOAEE. The first 76 
characters of each area will be printed. At least 1 and a 
maximum of 9 areas should be specified. 
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Notes ; 

1. The status cede error routine will return to your program on 

request. This may be valuable in a test environment; however, for a 
production program the abnormal termination option should be 
selected . 

2- For PL/I, you should declare DFSOAEE to be an ENTBY with OPTIONS 
(ASSIMELIB) . Moreover, ycu should pass the actual PCE-name and not 
the pointer variable on which the PCE is based, unlike calls to 
Dl/I. 

For the programming details refer to the sample application programs in 
IMSVS.PBIMESBC. 

ASSEMBLES PBCGBAMKING CCNSIEFBATICNS 

When writing a EL/I application program in Assembler, the following 
should be cbserved (for an example see program DFSOADEI in 
IMSVS.PBIMESBC) . 

• You should supply an entry statement: 

EN1BY DLITASM 

• At entry to your program, register 1 contains the address of a list 
of PCE addresses in standard CS/VS convention- The high order tyte 
of the last fullword ir this address list is set to X^O 1 to 
indicate end of list. You should not change this list but save 
these PCE addresses for later reference. 

• Each call statement should be coded as follows: 

f , n 

| CALI ASMTE1I, (functicn, (pebreg) ,icarea,ssa1, ....-, ssan) ,VL | 
i. .................................. ...... — ........................j 

where: 

function is the name cf a field containing the EL/I call functicn 

pebreg is the register containing the PCB address 

ioarea is the name of input/cutput area 

ssal-ssan are the names of segment search arguments 

• After each call, you should check the status code as returned in the 
FCE. On errcr conditions ycu should invoke a status code error 
routine. 

• At the end of your program, ycu should always return to DL/I- You 
can set a return cede, but if DL/I has encountered an error 
condition (for example, data base I/C error), your return code will 
be overriden by DL/^s. 

Several Assembler routines are provided with the sample programs in 
IMSVS.PBIMESBC. Most of these can be used as they are, or with minor 
modifications depending on ycur installation's standards. 
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The following general routines are available: 

• DFSOAER, a status code error routine, discussed earlier in this 
chapter- 

• DFSOSST, a general data base buffer ecoI statistics print routine; 
see the discussion cf the STAT call in this chapter. 

JCL for Assembly and Linkage Editing 

The Sample JCL for assenfcly and linkage editing can be found in job 
//SAME034 in IMSVS. EFIEEJCB, which can be used to assemble and link-edit 
the sample data base lead program. 

COECL FBOGBAMMING CONSIDERATIONS 

Ihere are a few considerations that apply when you are coding DL/I 
programs in CCBCL. Eefer to figure 4-17 for this discussion, Ibe 
numbers between parenthesis in the text below refer to the corresponding 
code lines in Figure 4-17- Specific parameter values and formats are 
explained elsewhere throughout this chapter. 



10 DIVISION. 
ENVIRONMENT DIVISION. 

DATA DIVISION. 

KOPKING-STORAGE SECTION. 

77 GU-FUNC PIC XXXX VALUE 
GN-FUNC PIC XXXX VALUE 
ERROPT PIC XXXX VALUE 
DEPRID PIC X(8) VALUE 



77 
77 
77 
01 
01 



'GU 

•GN ' . 

•1 

'DEPROR01' 



IOAREA PIC X(256) VALUE SPACES. 

SSA001-GU-SE1PART. 

02 SSA001-BEGIN PIC X(19) VALUE 'SE1PART (FE1PGPNR 

02 SSA001-FE1PGPNR PIC X(8). 

02 SSA001-ENO PIC X VALUE ')'. 



LINKAGE SECTION 
01 D1PC. 

02 

02 

02 

02 

02 

02 

02 

02 

02 



D1PCDBDN PIC X(8). 
D1PCLEVL PIC 99. 
01PCSTAT PIC XX. 
D1PCFROC PIC XXXX. 
D1PCRESV PIC S9(5) COMP. 
D1PCSEGN PIC X(8). 
D1PCKFBL PIC S9(5) COMP. 
D1PCNSSG PIC S9(5) COMP. 
D1PCKFBA PIC X(20). 



PROCEDURE DIVISION. 

ENTRY 'DLITCBL' USING D1PC. 
CALL 'ILBOSPI0'. 

CALL 'CBLTDLI' USING GU-FUNC, D1PC, IOAREA, 

SSA001-GU-SE1PART. 

CALL 'CBLTDLI' USING GN-FUNC, D1PC, IOAREA. 
IF D1PCSTAT NOT = ' ' , 

CALL 'DFS0AER' USING D1PC, DERRID, IOAREA, ERROPT, 

MOVE +4 TO RETURN-CODE. 

CALL 0FS0AST USING D1PC. 

CALL 'ILBOSPI0'. 
GOBACK. 

Figure 4-17. COEOL Batch Program Structure 



0000001 

0000002 
0000003 
0000004 
0000005 
0000006 
0000007 
0000003 
0000009 
0000010 
0000011 
0000012 
0000013 
0000014 
0000015 
0000016 
0000017 
0000018 
0000019 
0000020 
0000021 
0000022 
0000023 
0000024 
0000025 
0000026 
0000027 
0000028 
0000029 
0000030 
0000031 
0000032 
0000033 
0000034 
0000035 
0000036 
0000037 
0000038 
0000039 
0000040 
0000041 
0000042 
0000043 
0000044 
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• The DL/I function codes (7), IOAREA (11), and Segment Search 
Arguments {12) should be defined in the Working-Storage Section of 
the Eata Division- Typically, either the IOftBEA would be REDEFINED 
tc provide addressability tc the fields of each segment, or separate 
IOAREAs would be defined for each segment. 

• The Program Communication Elccks (PCBs) should be defined in the 
Linkage Secticn cf the Data Division (18) . Hhen there are multiple 
database structures (thus multiple PCEs) in a program, there must be 
one PCB defined in the linkage Secticn for each PCB in the PSE. 
However, these PCEs need not be in any specific order. 

• An ENTBY statement (30) should be coded at the entry to your 
program. A parameter of the USING clause should exist for each 
database structure (PCB) that is used in your program. The order of 
PCBs in this clause must be the same as specified in the Program 
Specification Block (PSB) for your prcgram. 

• Each DL/I CALL statement should be coded as in statement (33). The 
parameters of the EL/I call are explained elsewhere in this chapter, 
and differ in number fcr different functions. 

• The status code in the PCB should be checked after each call (37). 
The status-code error routine is discussed below (38) . 

• At the end of processing, control must be returned to DL/I via a 
GCEACK statement (44) • If ycu wish, you may set the COECL 
•RETURN-CODE 1 (39). If EL/I detects no errors, and thus does not 
set the return code, the COBOL »RE TORN-CODE* value will be passed on 
to the next jcb step. 

• The Status-Cede Errcr Bcutine, DFSOAER (38) may be called if an 
unexpected status code is returned by ycur program. This routine is 
discussed earlier in this chapter. 

• The Euffer-Pool Statistics Print Routine, EFSOftST, (41) may be 
called from your program. Its usage is discussed in this chapter 
under the STAI call. 

• The Symbolic-Debugging facility of COECL can be used. A call tc 
COEOL module ILBOSPIO (21) shculd be made immediately after entry to 
and before exit from your program. This facility is further 
described in the Programmers Guide for your COBOL program product. 

• The sample programs in IMS VS. PRIMESRC use a form of structuring. 
This is not classical "structured programming", but the examples are 
modular and should be readily maintainable. 

JCL_Fcr_ComEile_And_Linkage_ Editing 

Sample JCL fcr compiling and link editing a COEOL program can be fcund 
in job //SAMP14C in IMSVS.PRIMEJOB. 

JCL_fpj:_P£oc|ram_ Execution 

Job //SAMP 17 1 in IMSVS.PRIMEJOB shows the JCL for the Parts Inventory 
report program. Job //SAHP173 shows the JCL for the Purchase Order 
program. 



Data Ease Processing 4.33 



PL/I FEOGBAMMING CCKSIEEB AIICNS 

This section refers to Figure 4-18- The numbers between parenthesis in 
the text refer tc the corresponding code lines in Figure 4-18- 

When EL/I invokes your PL/I program it will pass the addresses, in the 
fern cf pointers, to each ECE required for execution- These will be 
passed in the sane sequence as specified in the PSB. To use the PCEs, 
you must code parameters in your PEOCEDUEE statement, and declare them 
to have the attribute POINTEB. In the example in Figure 4-18, EC_PTB 
and DB_PTB are specified in the PEOCEDUEE statement (6) and declared 
P0IN1EB variables (15 and 16). These pointer variables should be used 
in declaring the PCEs as BASED structures (18 and 21) , and in calling 
DL/I (55) - 

The format of the Pl/I CAII statement to invoke EL/I (55) is: 

CALL PLITD1I (parmccunt,f unction, peb-ptr, io-area,ssal,,- ... ,ssan) ; 

where: 

parmccunt is the number of arguments in this call following this 

argument. It must have the attributes FIXED BINABY 
(31), See (38). 

function is the DL/I function code. It must be a fixed length 
character string of length 4. 

peb-ptr is a pointer variable containing the address of the 
PCB. This is normally the name of one of the 
parameters passed to your program at invocation. 

io-area is the storage in your program into/from which DL/I 

is to stcre/fetch data. It can be a major structure, 
a connected array, a fixed-length character string 
(CHAB(IOC)), an adjustable character string 
(CHAE(N)), a pointer to any of these or a pointer to 
a miner structure. It cannot be the name of a minor 
structure or a character string with the attribute 
VABYING. 

ssal,.«. is one or more optional segment search arguments. 

Each SSA argument must be one of the same PL/I forms 
allowed for io-areas, described above. See (47) in 
the example. 

Upon completion of your program, you should return either via a BETUEN 
statement or ty executing the main procedure END statement. 
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/*- 

/« 

/*- 



SAMPLE PL/I PROGRAM 



PE2PORD: 

PROCEDURE (DC_PTR,DB_PTR) OPTIONS (MAIN); 



/*. 



DECLARE 



*/OOOO0Ol 

«/0000002 

*/0000003 

0000004 
0000005 
0000006 
0000007 

DECLARE POINTERS AND PCBS */0000008 

0000009 
0000010 
0000011 
/* DL/I WILL BE CALLD*/0000012 
/* STATISTICS PRINT */0000013 
/* STATUS CODE PRINT */0000014 



/* CMPAT IN PSB 
/* ORDER DB FCB 



/* NOT USED IN 
/* BATCH DL/I 



PLITDLI ENTRY, 

DFSOAST ENTRY OPTIONS (ASSEMBLER INTER), 

DFSOAER ENTRY OPTIONS (ASSEMBLER INTER), 
DC_PTR POINTER, 
DB^PTR POINTER, 

1 C1PC BASED (DC_PTR), 
2 DUMMY CHAR (32), 

1 D1PC BASED (DB PTR ) , 
2 D1PCDBDN CHAR (8), 
2 D1PCLEVL CHAR (2), 
2 D1PCSTAT CHAR (2), 
2 D1PCFROC CHAP (4), 
2 D1PCRESV FIXED BINARY (31), 
2 D1PCSEGN CHAP (6), 
2 DIFCKTBL FIXED BINARY (31), 
2 D1PCNSSG FIXED BINARY (31), 
2 D1PCKFBA CHAR (14); 



/* DECLARE FUNCTION CODES, I/O AREA, CALL ARG LIST LENGTHS 

DECLARE 



*/0000015 

*/0000016 

0000017 

«/oooooie 

*/0000019 
0000020 
*/0000021 
*/0000022 
*/0000023 
*/0000024 



IO_AREA CHAR (256), 

GU_FUNC STATIC CHAR (4) INIT ('GU'), 
FOUR STATIC FIXED BINARY (31) INIT (4), 
ERROPT1 CHAR (4) INIT ('0') STATIC, 
ERPOFT2 CHAR (4) INIT ('2') STATIC, 
DERRID CHAR (8) INIT ('DERROR01') STATIC? 



/* PHASE 2 ORDER DB 
/* DBD NAME 
/* SEGMENT LEVEL 
/* STATUS CODE 
/* PROCESSING OPTN */0000025 
/* RESERVED */0000026 
/* SEGMENT NAME */0000027 
/* KEY FEEDBACK LNG»/0000028 
/* NO. OF SENSEGS */0000029 
/* KEY FEEDBACK */0000030 
0000031 
*/0000032 
0000033 
0000034 
0000035 
*/0000036 
*/0000037 
*/0000038 
*/0000039 



/* DECLARE SEGMENT SEARCH ARGUMENT (SSA) 

DECLARE 

1 SSA007_GU_SE2OPDER, 

2 SSA007_BEGIN CHAR (19) INIT < ' SE20RDER( FE20GREF ='), 

2 SSA007_FE20GREF CHAR (6), 

2 S5A007 END CHAR (1) INIT (•)'); 



/* I/O AREA 
/* CALL FUNCTION 
/* ARG LIST LENGTH 
/* OPTN FOR DFSOAER 
/* FINAL OPTN-DFS0AER*/0000040 
/* ID FOR DFSOAER */0C00041 
0000042 

- ORDER SEGMENT «/0000043 

0000044 
0000045 
0000046 
0000047 
0000048 
0000049 
0000050 
0000051 

/* PROCESSING PORTION OF THE PROGRAM */0000052 

0000053 
SSA007 FE20GREF = 'XXXXXX'! 
CALL PLITDLI < FOUR ,GU_FUNC ,0B_PTR , IO_ AREA, 

SSA007 GU SE20RDER); 
IF D1PCSTAT -= ' ' THEN 

CALL DFSOAER (D1PC , DERRID ,10 AREA.ERROPT1 ) ; 

CALL DFSOAER ( D1PC, DERRID ,IO~AREA,ERROPT2 ) ; /* FINAL CALLTO ERR*/0000059 

0000060 

/# BEFORE ENDING, LIST BUFFER POOL STATISTICS */0000061 

0000062 
CALL DFSOAST (D1PC); /* CALL STATS PRINT */0C00063 

0000064 

/# RETURN TO CALLER */0000065 

0000066 
END PE2PORD5 0000067 

0000068 



/* SET SSA VALUE 
/* THIS CALL WILL 
/* RETURN 'GE' STAT 
/* CALL ERROR PRINT 



*/0000054 
*/0000055 
*/0000056 
*/0000057 
0000058 



/*- 

/* 

/«- 



END OF PL/I SAMPLE PROGRAM 



-*/0000069 
*/0000070 
-*/0000071 



Figure 4-1 8™ PL/I Batch Program Structure 

• Programs that are CS/VS subtasks of an application program called ty 
IMS/VS must not issue DL/I calls. If they do, the results will be 
unpredictable- Hith PI/I# whenever PL/I multitasking is used, all 
tasks, even the apparent main task, operates as subtask to a hidden 
PL/I control task, PL/I tasking is therefore not allowed in an 
IMS/VS program- 
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• Because the nornal irethcd of passing parameters to a main procedure 
is not available in IMS/VS, you must use the PLIXOPT facility tc 
specify PL/I run-tine options. See the PL^I Optimizing Compiler 
JEl£3I5!!!©lls Suide # SC33-CCC6, for details. 

• You should consider using the PL/I Fast path 
Initialization/Termination Option in an IMS/VS EB/DC environment. 
Consult the appropriate PL/I documentation for details, 

2§ifi3-.£iJ_Saj£le_Rcutin€s 

The Status Code Errcr Print program (DFSOAER) may be called from EL/I 
programs as shewn in (9). Similarly, the Statistics Print program 
(EFSOAST) can fce called. See (10)- See "Status Code Error Routine" and 
"The STAT Call" discussions earlier in this chapter for a description of 
the formats for these calls. In both cases, no parmcount argument i f s 
allowed, as is reguired in the DL/I call. In addition, the name of the 
PCB must be passed rather than the name of the pointer variable en which 
the PCB is based. EFSOAER and DFSOAST should be declared as ENTRY 
constants with OPTIONS (ASSEMBLER) . 

iiJ3iS»JJiting -p PL/I_Piograi£-icr_DL/I 

The BL/I language interface program must be included at link-edit time. 
In addition, the normal entry point for PL/I Optimizer programs 
(PLISTART) must be overridden, specifying PLICALLA. The sample job 
//SAMP254 linkage editor step shows an example of the reguired linkage 
editor control statements- They are: 

INC10EE ddname (EESOAEE) SC Error Print 

INCLUDE ddname JBFSOAST) Statistics Print 

INCLUDE RESLIE(PLITDLI) language Interface 

ENTRY PLICALLA 

NAME load-module-name (R) 

The above three INCLUDE statements can be omitted if the modules or 
aliases are members cf libraries which are concatenated as part of the 
ddname SYSLIB during link-editing. References to them will be resolved 
via automatic library call. When link-editing EL/I-F programs, the load 
module ENTRY must be specified as either IHESAPE (OPT=0) or IHESAPD 
(0PT=1) . 

SAMELE PHASE 1 EECGJAMS 

Besides the saaple data base load program DFSOADBL, two batch programs 
both in COBOL and PL/I are included in IMSVS.PRIMESRC. 

Program FE1CEINV (member EFS1CINV for COEOL, or DFS1PINV for PL/I in 
IMSVS.PRIMESRC) is a read only parts inventory report program. This 
program can be compiled with job //SAMP140 (COBCL) or //SAME150 (EL/I) 
in IMSVS.ERIMEJGE. Job //SAHE171 in IMSVS. PRIMEJOB can be used for its 
execution. 

Program PE1CPPUR (member DFS1CPUR for COBCL, or DFS1EFUR for EI/I in 
IMSVS.PRIMESRC) is an update parts purchase order sample program. This 
program uses the batch checkpeint/restart facility of IMS/VS. The 
program can be compiled with job //SAME141 (COEOL), or //SAMP151 (PL/I). 
Job //SAMP173 can be used fcr its execution, and job //SAMP 178 for its 
restart. 
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For more details on these programs and their operation you should 
consult their listing. 

Notice that the data base update jobs, specify a log data set in the 
//IEFRDER DD statement. For a discussion of the EL/I logging facility, 
refer to Chapter 6, "Eata Base Recovery." 

I1CCESSING_HI2H_L0GICA1_HELA5I0N SHIPS 

Generally, there is nc difference between the processing of physical 
data bases and logical data bases; all call functions are available for 
both. Some considerations dc apply, however, when accessing a logical 
child or a concatenated segment. For a definition of these terms see 
"DL/I Logical Relationships" in Chapter 2. 

ACCESSING A LOGICAL CHILD IN A PHYSICAL DBD 

When accessing a logical child in a physical DBD, you should remember 
the layout of the logical child™ It always consists of the logical 
parent concatenated key (tfcat is, all the consecutive keys from the root 
segment dewn to and including the logical parent) plus the logical child 
itself; the intersection data {see Figure 2-10) • This is especially 
important when inserting a logical child, you will also get an IX 
status code when you try tc insert a logical child and its logical 
parent does not exist (except at initial load time). This will 
typically happen when you forget the LPCK in front of the LCHILD. 

Note: In general, physical data bases should not be used when 
processing logical relationships. 

ACCESSING SEGMENTS IN A ICGICAI DBD 

The following considerations apply for each call function when accessing 
segments in logical BBEs. 

Ret£ieve_Calis 

These calls function as befcre with the same status codes. Remember, 
however, that the concatenated segment always consists of the logical 
child segment plus, optionally (dependent on the logical DBD) , the 
destination parent segoent (see Figure 2-13). 

E§El§ce_Calls 

In general, these calls function the same as before. When replacing a 
concatenated segment ycu say replace both the logical child segment and 
the destination parent. Remember, however, that you never can change a 
seguence field. The following sequence fields can occur in a 
concatenated segment (see also Figure 2-16) : 

• Destination parent concatenated key 

• Real logical child seguence field, (that is, the seguence of the 
physical twin chain as defined for the real logical child). This 
field can (partially) overlap the logical parent concatenated key. 

• Virtual logical child seguence field, (that is, the seguence of the 
logical twin chain as defined for the virtual logical child). This 
field can (partially) overlap the physical parent concatenated key. 

• The key of the destination parent itself. 



Data Base Processing 4.37 



If any of the above fields is changed during a replace operation, a DA 
status code will be returned, and no data will be changed in the data 
base. 

5§2§£§_Calls 

In general, these calls function the same as before. If, however, you 
delete a concatenated segmert (either of the tuc versions) , only the 
legical child and its physical dependents (that is, the dependents of 
the real logical child) will be deleted. The destination parent can be 
deleted enly via its physical path. In ether nerds: "The delete is not 
Frcpagated upwards across a logical relation." You can delete only those 
dependents of concatenated segments which are real dependents of the 
legical child. Examples: 

• If in the logical DED of Figure 2-25, a PABT segment was deleted, 
the associated STOCK, POHCHASE ORDER, DESCRIPTION, and CRCEE LINE 
segments are deleted, too. However, the associated CUSTOMER ORDER 
and SHIPMENT segments remain. 

• If in the logical EBD of Figure 2-26, a CUSTOMER CRDER segment was 
deleted, the associated CBEEB LINE and SHIPMENT segments are 
deleted, too. However, the associated PARI, STOCK, PURCHASE CRDER, 
and DESCRIPTION segments remain. 

Notice, the logical child (and its physical dependents) is always 
deleted whenever one of its parents is deleted. 

Nc_e: The above discussion of the DL/I calls is only applicable to our 
subset environment. This is explicitly related to the coding of the 
"RULES-" parameter as specified in Chapter 2 under the topic "Coding A 
Logical Relationship Ir A Physical DBD." 

Inser.t_Ca.lls 

Whenever you insert a concatenated segment, the destination parent must 
already exist in the data base. You can provide the destination parent 
together with the legical child in the ICAREA, but it is not used. 
Besides the normal status codes, an IX status code is returned when the 
destination parent dees net exist. 

LOADING DATA EASES KITH LCGICAL RELATIONSHIPS 

To establish the logical relationships during initial load of data bases 
with logical relationships, DL/I provides a set of utility programs. 
These are necessary because the sequence in which the logical parent is 
loaded is normally not the same as the sequence in which the logical 
child is loaded. Tc ccpe with this, DL/I will automatically create a 
wcrkfile whenever you load a data base which contains a logical child 
and/or logical parent. This workfile contains the necessary information 
to update the pointers in the prefixes of the logically related 
segments. Before dcicg so, the workfile is sorted in physical data base 
seguence with the Eigfix r.e§olution utility, (DFSURG10). This utility 
also checks for missing logical parents. Next, the segment prefixes are 
updated with the prefix update utility, (DFSURGPO) . After this, the data 
base(s) are ready to use. The above data base load, prefix resolution 
and update should be preceded by the £iejeorg,anization utility 
(DFSURPRO) . This utility generates a control data set to be used by 
data base load, DFSCRG10 and DFSURGPO. A detailed discussion of this 
data base load process and the associated utilities can be found in 
Chapter 5: "Data Ease Reorganization." 
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Both the phase 2 data bases EE2EABTS and EI20EEEE (Figure 2-24) can be 
loaded with the sample data base load program DFSOADBL- Job //SAHP270 
in IMSVS.PBIHEJOE shows the JCI for loading both data bases including 
all necessary DL/I utilities- 
Notice, there is no difference (in comparison to Phase 1) in the PABTS 
data base application (load) program. Ihis is because its user data has 
not been changed. Also, remember, the virtual logical child dees not 
actually exist and must not be leaded. However, the real logical child 
in the CUSIOMEB CBDEB data base must be loaded as it is defined in the 
physical BE20BDEB data base (that is, including the logical parent »s 
concatenated key.) 

Notes : 

1. You cannot use a logical EEC when initially loading a data base 
(EBOCOPT=L (S) in the PCB) . 

2. The logical relationship in the PABTS data base could also be 
implemented with the aid of the DL/I reorganization utilities, thus 
avoiding a new initial lead of the PAB1S data base. This will be 
discussed in detail in Chapter 5: "Data Ease Beorganizaticn. " 

SAMPLE PHASE 2 PBOGBAMS 

Sample program PE2C0BDB (member DFS2COBD for COBOL, or DFS2PCBD for 
PL/I) in IMSVS.PEIMESBC shows the processing of the Phase 2 logical data 
bases as specified in Figure 2-25 and Figure 2-26. This is the customer 
crder processing program as defined in Chapters 1 and 2. Guidelines for 
its use are in the program listing. The program can be compiled and 
link-edited with job //SAMP2H2 (COBOL) or //SAMP254 (PL/I) and executed 
with job //SAMP272 in IMSVS. FBIMEJCB. 

PBOCESSING_KIIH_S|CCNpiBY_I!iE|XES 

For a review of the terminology and functions of secondary indexes see 
"DL/I Secondary Indexes" in Chapter 2. The sample environment to be 
used in this section is the phase 3 environment as introduced in 
Chapters 1 and 2. In discussing the DL/I calls in the following 
sections, you should refer to the phase 3 sample EBDs of Figure 2-29. 

As discussed before, DL/I will always maintain the secondary index, 
whether or not the program taking the change is using the index. As a 
consequence, DL/I must have access to the index data bases when 
processing the main data base. Sc, the DD statements for the index data 
bases must be supplied in the OCI of every job which could change the 
secondary index. 

ACCESSING SEGMENTS VIA A SECCNDABY INDEX 

Mtr.ie^in^_Se.a,ments 

The same calls are used as befcre. However, the index search field, 
defined by an XDFLD statement in the DBD will be used in the SSA for the 
get unique of the root segment. It defines the secondary processing 
seguence. (See Figure 2-34, second FCE) . Figure 4-19 shows an example. 
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After the successful completion of this get unique call, the PCB and 
ICABEA look the same as after the basic GO of Figure 4-7, except that 
the key feedback area now starts with the purchase order number. 

When using the secondary processing sequence, consecutive get next calls 
for the PAETs segment will present only those parts with a EOBCHASE 
ORDER segment, the sequence being the purchase order number. It is as 
if the purchase order numfcer has taken over the role of root-key from 
the part number. As a conseguence, the key feedback area in the ICE now 
contains the purchase order numfcer instead of the part number. 
Fememfcer: The sequence cf the parts within one specific order is 
undetermined- In addition, you should not use a get unique with the part 
numfcer for accessing the parts segment with the secondary processing 
PCB. This would result in a full data base scan. 

If both the primary and the secondary processing sequence are needed in 
one program, ycu should use two PCBs as in Figure 2-34. 



r 

77 GU-FUNC PICTURE XXXX VALUE »GUbb«. 

01 SSi005-GU-SElPARl. 

02 SSA005-EEGIN PICTURE X(19) VALUE • SE1 PABTb (FE3PSID1 1«' . 
02 SSA005-EE3PSID1 PICTURE X (8) . 
02 SSACC5-END PICICRE X VALUE •)'- 

01 IOAREA PIC1CRE X(25€). 

MOVE POBDER-NUMBEB 10 SSA CC5-FE3PSID 1 . 

CALL •CBLTDLI 1 USING GU-FUNC ,PCB-NAME, IOAREA, SSA005 -GU-SE1 EART. 

STATUS^ CODES:. 

fcfc: requested PART segsent has been moved to IOAREA 
GE: segment net fcund, reguested purchase order number not in 
data base 
other: error situation 

Figure 4-19. GU Call Using a Secondary Index 

Rejlacina,_Se2ments 

To replace segments in the indexed data base a combination of get hold 
and replace calls can be used as before. Again, no sequence fields may 
be changed. The index search fields, however, can be changed. If an 
index search field is changed, CL/I will automatically update the index 
data base via a delete eld and insert new pointer segment. 

Note: when using a secondary processing sequence, this could result in 
the later reaccessing of a data base record. 
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5©i§t;i5S- Segments 

When using a secondary processing sequence, you cannot delete the index 
target segment (tfcat is, the rcot segment) . If you have a need to do 
so, you should use a separate ECE with a primary processing seguence. 

l2i§£liS3_ Segments 

Again, when using a secondary processing seguence, you cannot insert the 
index target segment- In all ether cases, the I SET call will function 
as before. 

SAMELE PHASE 3 PEOGEAMS 

Program EE3CPFUB (member DFS3CFUE for CCECl, or DFS3FPUE for FI/I) in 
IMSVS.FEIMESEC, shows the use of a secondary index for the purchase 
order processing sample. This program processes transaction TE3ECINC. as 
defined in Chapter 2. For more details, see the program listing. This 
program can be compiled and link-edited with job //SAMP341 (COBOL) or 
//SAMP351 (PL/I) in IMSVS.PEIMEJOB . It can be executed with job 
//SAMF373. 

SECCNDABY INDEX CBEATICN 

A secondary index can fce created during initial lead of the indexed data 
base cr later. The secondary index data base is created with the Dl/I 
reorganization utilities. Ho application program is reguired for this 
creation. Chapter 5, "Becrgarization," will cover this in detail. 

|A2CJH_CHECKPCINT^BJSTAET 

The batch checkpeint/restart facility of DL/I allows long running 
programs to be restarted at an intermediate point in case of failure. 
At regular intervals (CHKP calls) during application program execution, 
DL/I saves, en its log tape, designated working storage areas in the 
user's program, the position cf GSAM data bases, and the key feedback 
areas of non-GSAM data bases. 

For each checkpoint, a checkpoint ID (message DFS681I) will be written 
to the OS/VS system console and to the job system output- 

At restart, the restart checkpoint ID is supplied in the PAEM field of 
the EXEC statement of the job. DL/I will then reposition the GSAK data 
bases and restore the designated program areas. This is accomplished 
with a special restart call (XEST) which must be the very first DL/I 
call in the program. At initial program execution, the XEST call 
identifies the potential trcgram areas to be checkpointed by later CHKP 
calls. 

USING THE XEST ANE CHKP CALLS 

To utilize the checkpoint/restart function of DL/I for batch programs, 
you should consider the following guidelines: 

1. All the data sets that the program uses must be EL/I data bases. 

gsam should be used for sequential input and output files, including 
SYSIN and SYSCCT. Any other file cannot be repositioned by DL/I and 
can result in duplicate cr lest output. 
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2. Th€ GSAM cutput data sets should use DISP= (NEW, KEEP, KEEP) for the 
initial run and DISP= (OLD, KEEP, KEEP) at restart (s) . 

3- SYS0C1 should not be used directly. The output should fc€ written tc 
a GSAM file (as in 2) and be printed with an additional jobstep. 
IEEGENER can be used for this purpose. 

4. The first call issued to EL/I must be a XRST call. Its format will 
be discussed later. 

5. The frequency cf the checkpoint call is your choice. A basic 
recommendation is one checkpoint for every 50 to 500 update 
transactions- It is good practice to program for an easy adjustment 
of this freguency factcr. 

6. After each checkpoint call, you must reposition yourself in the 
non-GSAM data bases by issuing a get unique call for each of these 
data bases. Repositioning of GSAM data bases is done by DL/I, and 
you should proceed with a get next (input) or an insert (cutput) 
call. 

lij€_IL§star.t_Ca < ll 

Upon receiving the restart call (XRST) , DL/I checks whether a checkpoint 
ID has been supplied in the PAFM field of the EXEC card or in the 
workarea pointed to by the XRST call. If no ID has been supplied, a 
flag is set to trigger storing cf repositioning data and user areas on 
subsequent CHKP calls (that is, DL/I assumes that this is the initial 
program execution, not a restart) • 

If the checkpoint at which restart is to occur has been supplied, the 
IMS/VS batch restart routine reads backwards on the log defined in the 
//IMSLOGR DD card tc lecate the checkpoint records. Dser program areas 
are restored. 

The GSAM data bases active at the checkpoint are repositioned for 
sequential processing. Key feedback information is provided in the PCE 
for each data base active at the checkpoint. The user program must 
reposition itself on all ncn-GSAM data bases, just as it must do after 
taking a checkpoint. 

Ihe format of the XRST call is: 

COECL: 

CALL •CBLTDLI 1 using call-func,IOPCE-name,I/0-area-len, work-area 

[ ,1st-area-len, Ist-area,. . ., nth-are a- len, nth- area]. 



EL/I: 



CALL PLITDLI (parmcount ,call-func,IOPCB-name,I/0-area-len,work-ar 
[ , 1st -area -len, 1st-area,«. . ., nth -area- len, nth- are a]) ; 



ASSEMELEE: 



CALL ASHTDLI, (call-f unc,ICPCB-name,I/0-ar ea-len,work-area 

[ , 1st-area-len, Ist-area,- . ., nth- are a- 1 en, nth- area]) , 



where: 



parmcount 

is the name cf a binary fullwcrd field containing the number of 
arguments following. EL/I only. 
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call-func 

is the name of a field which contains the call function 'XBST*. 

ICFCB-name 

is the name of the I/O PCB or the "dummy" I/O FCB supplied by 
the CMFAI option in PSEGEN (C1PCE in the sample programs). 

I/O-area-len 

is the name cf the length field of the largest I/C area used by 
the user program; must be a fullword. 

work-area 

is the name of a 12 byte work area. This area should be set to 
blanks (X'tO*) before the call and tested on return. If the 
program is being started normally, the area will be unchanged. 
If the program is being restarted from a checkpoint, the ID 
supplied by the user in that CHKP call and restart JCI will be 
placed in the first 8 bytes. If the user wishes to restart 
from a checkpoint using a method ether than IHS/VS Program 
Bestart, he may use the XBST call to reposition GSAM data bases 
by placing the checkpoint ID in this area before issuing the 
call. This IE is the 8-byte left-aligned, user supplied ID. 

1st-area-len 

is the name cf a field which contains the length of the first 
area to be restored; must be a fullword. 

Ist-area 

is the name of the first area to be restored 



nth-area-len 

is the name of a field which contains the length of the nth 
area to be restored (sax n=7) ; must be a fullword. 

nth-area 

is the name of the nth area to be restored (max n-7). 

Notes: 

1. The number of areas specified on the XPST call must be egual tc the 
maximum specified en any CHKP call. 

2. The lengths cf the areas specified on the XRST call must egual to or 
larger than the lengths of the corresponding (in sequential crder) 
areas of any CHKP call. 

3. The XBST call is issued only once and it must be the first request 
made to DL/I. 

4. The only correct status code is bb; any other implies an errcr 
cendition. 

5. All "area-len" fields in PI/I must be defined as substructures. The 
name of the major structure should, however, be specified in the 
call. 



Example: 



DCl 1 I/C-ABEI-IIK, 

2 L NTH FIXED BIN (31) INIT (length) ; 
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lh€_ChecJc£cint_Call 

When EL/I receives a CHKP call from a program which initially issued a 
XES1 call, the following actions are taken: 

• All data base buffers modified by the program are written to DASD. 

• A log record is writter. with the checkpoint ID; message EFS601I is 
written, specifying this ID to the OS/VS system console and job 
sysout. 

• The user-specified areas (for example, application variables and 
ccntrol tables) are recorded on the DL/I log tape. They should be 
specified in the initial XBST call. 

• The fully-qualified key of the last segment processed by the program 
on each DI/I data base is recorded on the DL/I log tape. 

Ihe format of the CHKE call is: 

CCEOL: 

CALL * CBLTDLI' using call-f unc, IOPCB-name ,1/0-area-len, I/O-area 

[ , 1 st- area- 1 en, 1st -area,.. .,nth-area-len,nth-area ]) . 



PL/I: 



CALL PL IT EL I (pan count , call- f unc, IOPCB -name, I/O- area- 1 en , I/O-area 
[ , 1st-area-len, 1st -area , . • . ,nth-area-len ,nth-area ]) ; 



ASSEMBLES: 



CALL ASMTELI, {call- f unc, IOPCB-name,I/0-area-len, I/O-area 
where: area- 

parmccunt 

is the name of a binary fullword field containing the number of 
arguments following; EL/I only. 

call-func 

is the name of a field with the call function 'CHRP 1 . 

IOPCE-name 

is the name of the I/C FCB or dummy PCE in batch. 

I/O-area-len 

is the name of the length field of the largest I/C area used by 
the application program; must be a fullword. 

I/C-area 

is the name of the I/O area. Ihe I/O area must contain the 8 
byte checkpoint ID. This is used for operator or programmer 
communication and should consist of EBCDIC characters. In 
PL/I , this parameter should be specified as a pointer to a 
major structure, an array, or a character string. Eecommended 
format: 

EMMttnnnn 

MMMM = 1 character program identification 

nnnn = M digit checkpoint sequence number, 
incremented at each CBKP call- 
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1st-area-len (optional) 

is the name of a field that contains the length of the first 
area to checkpoint; must be a fullword. 

1st-area (optional) 

is the name of the first area to checkpoint 



nth-area-len (optional) 

is the name of a field that contains the length of the nth area 
to checkpoint (iax v.=l) ; must be a fullword. 

nth-area (optional) 

is the name of the nth area to checkpoint (max n=7). 

Notes: 

1- The cnly correct status code in batch is bb; any other specifies an 
error situation. 

2. Before restarting a program after failure, you always must first 
correct the failure and recover your data bases. This is discussed 
in Chapter 6: "Data Base Recovery." 

3. Ycu must reestablish your position in all IMS/VS data bases (except 
GSAM) after return from the checkpoint (that is, issue a get 
unique) . 

4. All "area-len" fields in PL/I oust be defined as substructures, see 
the example under note 5 of the XBST call. 

5. Eecause the log tape is read forward during restart, the checkpoint 
IE must te unigue for each checkpoint. 

USING GSAM WITH CHECKPOINT/RESTART 

Sequential Input files 

fit restart time, GSAM will reposition the sequential input file. For 
card input, SYSIN, the whole original input deck must be used. 

Sequential Output Files 

At restart time, GSAM will resume writing to the output data set 
(DISP=OLD), based on its output record count which was written on the 
DL/I leg tape. 

Note: Dl/I does not provide recovery of GSAM data sets. 

SAMPLE BATCH CHECKPOINT/RESTART PROGRAMS 

Program tE1CEPUB (member EFS1CE0R for COBOL of DFS1PPUR for PL/I) in 
IMSVS.PRIMESRC shews hew tc use the XRST and CHKP calls.. It also shows 
the use cf GSAM in this environment. Job //SAMP174 in IMSVS. FRIKEJCE 
can be used to execute this program. Job //SAMP178, shows the restart 
of this program. For details en exercising this program, see its 
program listing in IMSvS. PRIKES6C. 
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Note: Tc be compatible with IMS/VS data communication operation, the 
first PCB in the PSB of a batch program is a dummy PCE. (CKFAT=YES in 
the FSBGEN statement). 

DAlA_CCMM0NICAlICN_iFPlICATICK»IJCGFAJ3«ING 

In the following sections, we extend the IMS/VS data base processing 
into the online environnent . To process data bases online, message 
calls are added to the DL/I interface. Message calls are used to send 
messages tc terminals ar.d tc retrieve messages sent to IMS/VS from 
terminals. The data base calls discussed in the first part of this 
chapter remain the same. 

APPLICATION PEOGEAMMING AND MFS 

In our subset, we will exclusively use message format services (MFS) for 
the IBM 3210 Information Display System display and printer terminals. 
Therefore it is recommended that ycu are familiar with the section 
entitled "Message Format Service Overview" in Chapter 3 before using 
this section. 

APPLICATION FFCGEAM TYPES 

— — — —— — — — — — — — — -r— — —— — — — — — — — 

As defined in Chapter 1, "Introduction," there are three types of IMS/VS 
programs: 

• The Batch_Processing_Program (DLI) for batch processing of data 
bases. This program type is solely discussed in the first part of 
this chapter. 

• The Batch_Messace_|rccessing_Program (BMP) for batch processing of 
online data bases. 

• The Messa3j_Prcc€ssing_Prcgram (MPP) for processing transactions 
entered from terminals. 

There is no difference in the program structure of a DLI and BMP 
program. In fact, the very same program can be executed as a DLI or a 
BMP program if you follow the guidelines of the data base part of this 
chapter. 

GENEBAL MPP CONSIDERATIONS 

All data base functions previously discussed are available in the MFF, 
except: 

• GSAM data bases and OS/VS files cannot be used. 

• The XBST call cannot be used in a MPP. 

• The CHRP call sfcculd net be used in MPPs in our subset. 

• The STAT call should not be used in a MFP. Its results bear no 
direct relationship to the data base accesses of the MPP. 
Information en these accesses are available via the DC Monitor- See 
Chapter 9, "Optimization . " 
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GENERAL BMP CCNSIDEBA1CNS 

Any EL/I batch program written according to the guidelines in the data 
base part of this chapter can be executed as a BMP. 

The XBST and CHKE calls and GSAK for Non-EL/I files are required if the 
program is to be restartable. This is especially important for update 
programs. The reason is that the IMS/VS program isolation function will 
create an engueue element in main storage for every data base change. 
In addition, the old data base image will be saved on the dynamic log. 
Both the enqueue and the old data base image will be freed at the next 
§IIiSli£2Iiisat ion_j:cint . As each CHKP call constitutes a synchronization 
point, these resources are freed at each CHKP call. Our subset 
selection of the main storage pool for enqueue elements and the size of 
the dynamic leg is related tc a CHKP frequency of one for every 100 or 
less data base changes. 

M£iticna!_CHO_Status_Code_In_A_BMP 

in comparison to the IHS/KS-DB system, one additional status code should 
be expected after the CHKP call in a BMP: "XD"., 

This XD status cede signals that the IMS/VS control region is shutting 
down. No more EL/I calls are accepted by the CTL region from the EME. 
The BMP should terminate as soon as possible. 

MEI_SIB0C30BE - .AKE - IJSS^VS - I|T|EF2CJ 

When the 1HS/VS Lata Communication feature is used, application programs 
can communicate with devices as well as access data bases. The program 
communicates logically with a device through IMS/VS rather than directly 
to the device. This is made possible by the IMS/VS concept of logical 
terminals. A logical terminal is a name related to the actual device, 
the physical terminal. Cne physical terminal can have one or more 
associated logical terminal names. The logical terminal name or names 
for each physical terminal are defined by the IMS/VS system programmer 
during IMS/VS system definition. 

The logical terminal concept allows an application program to be 
independent of the characteristics of a particular physical terminal. 

Generally, ycu need not be concerned with the actual location or address 
of the device. If a physical terminal becomes inoperative, its 
associated logical terminal (s) can be reassigned to another physical 
terminal, thereby causing output messages to be sent tc another physical 
terminal. Also, each logical teminal can have unique security checking 
associated %ith it. 

To an application program, therefore, a logical terminal can be viewed 
as just another sequential data input source or output destination. The 
application program interface to the logical terminal is through 
essentially the same call interface mechanism that was described for 
data base access. Access to a data base requires the use of a data base 
Program Communication Elock (DB-PCB) . Accordingly, communications with 
a DC device requires the use of a data communication PCB (DC-PCB). 

MPPs normally reference both EE-ECEs and EC-PCEs, and must contain a 
mask to handle each PCB type. Figure 4-20 shows that the MPP views 
terminals and data from a logical view point- Any changes to the 
physical terminal configuration cr to the actual data structures have a 
minimal effect on the application program- 
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Figure 4-20. PCB Masks fcr a MPP 



As for the batch system, bcth the DB PCBs and the DC PCBs are part of 
the program specification block (PSB). A PSB is required for each MPP 
and is created by the PSBGEN utility- See Chapters 2 and 3. 

EC PCEs 

There are two types of DC PCBs — the I/C PCB and the alternate ECB. An 
I/C PCB is always provided by IMS/VS to the application program that 
executes in a EC environment. Alternate PCBs are optional and must be 
coded separately in the PSB. 

IZ£_fCB 

The 1/0 PCB must be used by the MPP to: 

• Obtain an input message frcm a terminal. 

• Return a reply tc the terminal that originated the input message. 
In our subset this will be required before new input is accepted 
from the terminal {response mode) . 

When IMS/VS receives an input message, it queues the message according 
tc transaction code and schedules the application program that processes 
that transaction. When scheduling the program, IMS/VS passes to the 
program the address 

of its I/C PCE plus the alternate PCB(s), if any, and the DB-PCB (s) , if 

any, defined in its PSB. Ihe I/O PCB contains the name of the logical 

terminal that entered the message (source) and can receive the reply 
(destination) . 

A£TEENJTE_PCE 

An alternate PCB must be used by the MPP to send an output message to a 
destination other than the terminal that originated the input message. 
An alternate PCB specifies a lcgical terminal destination. The 
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destination can be specified during PSB generation or during program 
execution. 

To be able to specify a destination during program execution, the 
alternate PCE must be defined as modifiable during PSB generation. When 
an application program uses modifiable alternate PCEs, the program must 
set the output message destitaticn before inserting the output message.. 

THE DC-PCE MftSK 

lo support communication with IMS/VS, the MEF must contain a DC-FCE 
mask. As shown in Figure 4-21, a DC-PCE mask distinguishes seven fields 
which are filled in by IMS/VS during each message call. These fields 
shculd net be changed by the program; they are only for reference. 



1 


LOGICAL TERMINAL NAME 
8 BYTES 


2 


RESERVED FOR IMS/VS 
2 BYTES 


3 


STATUS CODE 
2 BYTES 


4 


X 

u_ 

LU 

cc 

Z> 
Q_ 

z 


CURRENT DATE 
4 BYTES 


>< 

u. 

LU 
DC 
Q. 

t- 
D 
Q. 

z 


5 


CURRENT TIME 

4 BYTES 


6 


INPUT MESSAGE SEQUENCE NUMBER 
4 BYTES 


7 


MESSAGE OUTPUT DESCRIPTION 

NAME 

8 BYTES (I/O PCB ONLY) 



Figure 4-21. Layout of a DC-PCB Mask 



1. LOGICAL TERMINAL NAME — This field contains the name of the logical 
terminal that entered or will receive the message. The name is 1 to 
8 bytes long, left- justified, and padded with blanks. 

2. FESERVED ARE*. — A 2-byte area reserved for IMS/VS. 

3. STATUS CODE — A code showing the status of the result of a DC call 
is placed in this 2-byte field. When a call is executed 
successfully, this field is set to blanks. A non-blank status code 
is returned on an unsuccessful call. 

4 through 6. 



INPUT PREFIX -- Is available only for the I/O PCB. 
the input prefix is 12 bytes. 

4/ 4 byter - Julian date (YYDDD-packed 

decimal, right aligned) when 
the input message was completely 
received from the physical terminal. 



The length of 
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5. 4 bytes - Tims (hHKKSS.s-packed decimal) 

when the input message was 
completely received from the 
physical terminal. 

6. 4 bytes - Sequence number (binary) of 

the input message. Per terminal, 
since last IMS/VS start-up. 

7, MESSAGE 0C1PUT DESCRIPTION KAME — Is available only for the I/O 
PCE. This field has seaning only when output messages are sent to 
terminals that use the IMS/VS Message Format Service (MFS). 

When IMS/\S supplies the first segment of an input message, it fills 
this field with either the name of a message output description 
(MOD) or blanks. The MCD name can be changed by using the output 
MOD name parameter cf the DC output call that contains the first 
segment of an output message. This will be discussed later in this 
chapter. 

is £i P. L_E.x a m jj 1 S-5 JL.§_IO;:PCB_Mas.k 

The following example is an I/O PCB mask for COEOI message processing 
program. This mask would be found in the linkage section of the 
program* A mask for an alternate PCB would be similar but without the 
IN-PREFIX and KCD-NAME fields. 

DA3A DIVISION. 

LINKAGE SECTION. 

01 IC-PCB. 

02 LTEBK-NAKE PICTURE X (8) . 
02 ELI-RESERVE PICTURE XX. 
02 STATCS-CCEE EICTUEE XX. 
02 IN-PREIIX. 

03 JULIAK-DAIE PICTOEE S9(7) COMPUTATIONAL- 3. 

03 1IME-OF-DAY PICTURE SS (7) CCMEUTATIONAL-3. 

03 MSG-CCONT PICTURE S9 (7) COMPUTATIONAL. 

02 MOD-NAME PICTCRE X(8). 

I£ZI_l£am£ie_cJ_£_DC2ECS_Mas.k 

The following is an example for PL/I Optimizing Compiler message 
processing programs. A mask for an alternate PCB would be similar but 
without the IN_PREFIX and MOD_NAME fields. 

DECLARE 1 IO PCB BASED (IO_PCBPTR) , 

2 LTERK NAME CHARACTER (8), 
2 ELIJtESERVE CHARACTER (2), 
2 STATUS_CCEE CHARACTER (2), 
2 IN_PREFIX, 

3 JULIAN.DATE FIXEE DECIMAL (7) , 

3 TIME OF DAY FIXED DECIMAL (7), 

3 KSG.CCUNT FIXEE EINARY (31), 

2 MOD^NAME CHARACTER (8) ; 

ENTRY TO THE MPP 

The entry statement to a KFF must name the EC-PCBs and the EE-PCEs. The 
DC-PCBs must precede the DE-PCEs, and at least one DC-PCB must be 
specified to provide for the I/O PCB. 
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• The format for an CCECI program is: 

ENTEY 'ELITCEL 1 USING IC-ECB, ALT-PCE1, ALT-PCBn, EB-PCB1, DB-PCBn.. 

• The format fcr a PL/I cptiuizirig compiler program is: 

DLITPLI: PROCEEOBE (IC_PCBPTB ,ALT 1_PCBF1E , . . . ALTn_FCBFTB, 

EE1_ECEPTF,.. . EEn_PCEPTE) OPTIONS (MAIN); 

Programs that are OS/VS suttasks cf an application program called by 
IMS/VS must not issue EL/I calls. If they do, the results will be 
unpredictable. With PL/I, whenever PL/I multitasking is used, all 
tasks, even the apparent main task, operate as suttasks to a hidden FL/I 
control task. PI/I jtultitaskicg is therefore not allowed in an IMS/VS 
program. 

THE EC CALLS 

In addition to the DB calls, an MPP uses DC calls fcr the retrieval and 
insertion of messages. These EC calls must reference a EC-PCB as 
discussed in the previous section. Ihey relate to messages. 

A message is comprised of one or more segments. Figure 4-22 shows two 
messages: Message A is made up of Segment A1. Message B is made up of 
segments E1, E2 and B3. 

MESSAGE A MESSAGE B 



r -i r i 

| SEGMENT Al| | SEGHENT B1 \ 



L- ---------- -J 



| SEGMENI B2 | 

\ I 

| SEGMENI B3 ) 

L --J 



Figure 4-22- Single and Kulti Segment Message 

In our subset, using 3270 terminals and MFS, an input message will 
always be a single segment. The basic DC calls are: 

• GU (get unique) : to retrieve the first input message 

segment., 

• GN (get next): to retrieve the second input message 

segment, in our subset, only used for 
conversational programs. 

• ISEI (insert): tc insert a message segment into the 

output message queue. 

• CHNG (change destination) : to set the LTEEM destination cf an 

alternate FCB- 

The DC call format is slightly different frcm DB calls because there is 
no hierarchical structure with which to be concerned. SSAs (Segment 
Search Arguments) are not used for DC calls. 
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The format for a CCECI program is: 



r i 

I CALL »CELTELI» USING CALL-FUNC, IO-PCB, ICAF.EA. | 

t... ............................................... .....J 



The format for a EL/I program is: 



i i 

I CALL PL IT DL I JP ARM_COCNT,CALL_FUNC ,IO_PCBETF ,IOAEE A) ; ) 



When a transaction or input message is available for processing, the 
associated application program is scheduled into a message processing 
region. After feeing leaded, the program should issue a get unique (GO) 
call to obtain the first segment of its input message. A subsequent 
segment of that message is obtained with a get next (GN) call. GU and 
GN calls cannot be made tc an alternate EC6. 

If the program is serially reusable or reenterable between GU calls, GU 
calls can be issued for subsequent input messages until all messages are 
retrieved. If a prcgran is net serially-reusable or reenterable between 
GU calls, the program must terminate after each GU call so that it will 
be reloaded and re-initialized. 

It is highly recommended that the MPPs be at least serially-reusable. 
He will provide guidelines for this in the section " Easic MPP Flew" 
later on in this chapter. 

Get_Calls_JGU x _GNl 

The get calls are used tc retrieve segments of an input message. For 
each get unigue (GU) or get next (GN) call, one segment is returned to 
the application program. IMS/VS returns the retrieved segment to a work 
area defined in the application program. Since the length of a message 
segment is variable, the work area must be large enough to ccntain the 
longest segment expected ty the program. 

In addition, the program should check the length field of the input 
message. 

The first segment of an input message is obtained with a GU call against 
the I/O PCE. In response tc a GU call, IMS/VS returns the first message 
segment and fills in the following I/O PCB fields: 

• Source name (name of the logical terminal that originated the 
message) . 

• Status code. 

• Input prefix. 

• Message output description name (when present). 
The format for a CCECI program is: 



r t 

| CALL •CELTELI* USING GET-UNIQUE-F UNC, IC-ECB, ICAREA. | 
c- -------------------------------------- ------------ j 
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The format for a PL/I program is: 



r i 

I CALI PLI1D1I IE1K»_CCONT,GIT_ONICOE_FUNC,IC_PCEPTF,IOAREA); | 
i................. — - — ------------------------------- ....j 



STATUS COEES: 

bb: Call successful, message segment returned in IOAFEA 

QC: No more input messages for this transaction; the program must 
terminate 

other: Error situation 

For programs that process tultiple transaction codes, the text cf the 
input message can be examined tc determine the transaction code. 

The second segment of an input message is retrieved with a GH call. 
The format for a COBOL program is: 



r ------------- .........-.-.---.. - --.........-.--..^ 

| CALL •CBITDII* OSING GET-KEXT-FU KC, IC-ECE, IOABIA. | 
i---.-.---.- — -...--.-.-.....--.-. j 



The format for a PL/I program is: 



r -. -...-... ----------------------------------------------- ^ 

| CALL PLITDLI (FABM_CC0NT,GIT_KEXT_FUNC,IC_PCEPTB,IOABIA) ;| 

L-- ---I- ------------------------------------- J 



STATUS CODES: 

bb: Call successful, message segment returned in IOABEA 

other: Error situation 

Notes : 

1. The get next call should cnly be used for conversational 
transactions %ithin our subset. In that case, the GO call will 
retrieve the scratch pad area (SPA) and the GN call the actual input 
message segment. See the section on conversational programs later 
in this chapter. 

2. The program must check the status code after each call. The 
handling of error status calls is discussed later in this chapter. 

ISfert.Call^jISBl]. 

The insert call is used to build output messages. To build an output 
message in reply to the terminal that originated the input message, 
output message segments must be inserted to the I/O PCB. Output message 
segments can alsc be inserted tc alternate FCBs. If an alternate PCE 
has been defined as modifiable, a change call must be used before the 
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first insert call acainst the alternate PCB- The change call sets the 
destination of the output message. 

The ISBT call format is similar to that for message get calls. 

The fcrmat for a CCECI program is: 



r t 

| CALL 'CELTELI* USING ISRT-FUNC, DC-PCB, ICAREA, MCDNAME. | 

i ----_--.—, ----------------------------------------- -j 



The fcrmat for a PL/I program is: 



r i 

I CAIL PIITDLI |PARM_CCu"KT,ISET_FUNC,DC_PCBPTB, IOARE*.,rlODN AME) ; | 
i-- ------------ --* .---------.---..--....-j 



STATUS CCCES: 

bb: Call successful, message segment inserted 

ether: Error situation 

MCENAME is th€ label of an 8-byte field containing the name cf the 
message output description; the name must be left-justified and padded 
with blanks. 

This parameter should cnly be specified at the insert call cf the first 
segment of a message. Although the MODNAME may be already defined in 
the message input description (MID) used for the input message, it is 
recommended that you always specify it on the ISRT call of the first 
message output segment. It can also be used for the alternate FCEs. 

Note: For a detailed discussion on MIDs and MODs and their linkages, 
refer to the section "Message Fcrmat Service Overview" in Chapter 3, DC 

Design, 

Output message segments cannot be distinguished as first and subsequent 
segments by the insert call. Any required distinction must be made by 
the program. All message segments inserted to a given DC-PCE during the 
processing of a single input message are treated by IMS/VS as a single 
output message. 

At least one output message segment should be inserted to the I/C PCE. 

If the MPP has DE-PCBs defined, one or more data base calls may be 
executed. Ihe normal sequence of operation is to obtain the input 
message, issue data base calls based upen input message content, and 
create an output message based upon input message content and data 
obtained with data base calls. 

Change_Call_JCiNGl 

The change call is used tc set the destination of a modifiable alternate 
PCB to any valid logical terminal in the system- To use the change 
call, the alternate PCB must have been defined as modifiable during PSE 
generation. The destination of the modifiable PCB must be set with the 
change call before any segments are inserted. 
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The new destination remains set until either the application program 
issues another CfiNG, issues a GO, cr terminates. At that time, IMS/VS 
resets the destination to blanks. 

A change call for an altercate ECE cannot be issued while that PCB is 
being used to form a message. Therefore, multiple modifiable ECEs must 
be defined if messages are to be sent to several destinations while 
processing a single input iressage. 

The format for a COEOL call is: 



r _____ _ 

\ CALL , CB1_D1I' USING CHNG-FUKC, ALT-PCE, EEST-N-ME. | 

L__--_-_--__-_-_ __________________ _____ _ _j 



The format for a EL/I call is: 



r 1 

| CALL PLITDLI (TER IE,CI:NG_FONC,ALT_PCBPTR ,DEST_NAME) ; | 



STATUS CODES: 

bb: Call successful, destination set 

ether: Error situation 

The destination name parameter (EEST_NAME) specifies the name of an 
8-byte field containing the r.ame cf the logical terminal. The name may 
be 1- to 8-bytes long, uppercase EBCDIC, left- justified, and padded with 
blanks. 

IAS2C_M£SSAGE_IOBMATS 

The following message fcriats are presented to or received by IMS/VS 
with Message Format Service. For a detailed discussion of MFS, see 
Chapter 3. 

INEUT MESSAGE FCEKAT 

MFS edits input data from the terminal as defined in the device input 
format (DIF) and the corresponding message input description (MID) . 

The format of the one input message segment is: 



r -_ 

| LL | ZZ | TRANCODE 1 MFLDs | 
t — .-.«._ 



LL 



is a 2-byte binary field representing the total length of the 
message segment, including LL and ZZ. The LL value is provided by 
IMS/VS fcr input messages. 
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When PL/I is used, the LI field must be declared FIXED BINARY (31), 
a binary fullwcrd. The value contained in the LI field is the 



actual segment length minus 2 bytes. For example, if the input 
message segment is 2C bytes, LL is egual tc 18 and represents the 
sum of the lengths of II [U bytes minus 2 bytes), ZZ (2 bytes), 
TEANCOEE (9 bytes), and KFLDs (5 bytes). 

ZZ is a 2-byte field reserved fcr IMS/VS. 

TFANCOEE 

contains the transaction code as defined during IMS/VS system 
definition., Ihis field is 9 bytes; the transaction code is padded 
with blanks. The transaction code should be defined as a 9-byte 
MFLD literal in the KID. 

MFLDs 

are the message fields as defined in the MID. 

No t es : 

1. When the MFLD contains an attribute byte (ATTR=YES) , the first 
two bytes of this field are reserved for attribute data to be 
filled in by the MPP. 

2. Following our MFS guidelines, all MFLDs will appear in the 
message segment whether or not input data is received from the 
terminal. Therefore the input segment length is related to the 
transaction code. At least a check on maximum segment length 
should be dene by the MPP. 

CUTFGl MESSAGE fORKAT 

MFS edits output segments created by an application program into a 
device-dependent format suitable for the device to which the message is 
destined. Normally, the output segments contain no device-related data. 
All device-dependent information is provided when the message format is 
defined to MFS. 

An output message consists of all segments presented to IMS/VS with an 
ISRT call between a GU call to the I/C FCE and another GU call tc the 
I/O PCB, or normal program termination. 

The layout of the output segment is: 



r — 1 

\ LL | Z1 | Z2 I KFIDs I 



LL 

is a 2-byte binary field representing the total length of the 
message segment, including LL, Z1, and Z2. The value of LL equals 
the number of bytes in text (all MFLDs) plus 4. The application 
program must fill in this count. The segment must be less than 1388 
in our subset. Ibe segment length may be less than the length 
defined tc the MFS language utility- 

When PL/I is used, the LL field must be declared FIXED BINARY (31), 
a binary fullwcrd. The value provided by the PL/I application 
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Zl 



Z2 



program must represent the actual segment length minus 2 bytes- Fcr 
example, if an output nessage segment is 16 bytes, 1L is equal to 1U 
and represents the sum of the length of LL (4 bytes minus 2 bytes, 
Z1 |1 byte), Z2 (1 byte), and TEXT (10 bytes). 



is a 1-byte field reserved for IMS/VS; it must contain binary zeros. 



is a 1-byte field, which always should be a blank (bit 1 on, X^UO 1 ) 
in our subset, as ne only allow for one segment per logical=physical 
page. 

MFLDs 

are the message fields as defined in the message output descriptcr- 

All fields in output segments are defined as fixed length and fixed 
position. Fields can fce truncated cr emitted by two methods: The first 
method is by inserting the appropriate LL field, which truncates the 
segment. The second methed is by placing a NULL character (X^J 1 ) in 
the field. Fields are scanned left to right for a null character; the 
first null encountered temirates the field. 

Note: The above two methods will not clear the contents of protected 
fields en the screen. To completely clear such a field, a blank 
followed by a NOLL character (X # U03F') should be inserted in the first 
two positions of the field, that is, immediately following the attribute 
bytes, if any. Positioning of all fields in the segment remains the 
same regardless of null characters. Fields truncated or omitted are 
padded by MF£ with a program tab character for display terminals, and 
blanks for printer terminals. 

£Ynamic;_2£££ij3fi£€J!iodif icaticn_A$d_Qurscr_Ccntrol 

An option of MFS allows you tc dynamically modify the attributes of a 
device field, although attribute byte characteristics are normally 
specified in the MOD. This option reserves the first 2 data bytes of an 
output message field fcr attribute definition. You must add these 2 
bytes to the normal field length. Any errors detected in the 2-byte 
specification cause the entire reguest to be ignored and the attributes 
defined en the appropriate EF1E statement for the device format will be 
used. Any output field can have attribute bytes defined. 

The 2 attribute bytes are defined as follows: 

IX*e Bit 

0-1 Eoth bits are en, requests that 

the cursor be placed on the first position 
of this field en the device. Only the 
first MFLD with a cursor-positicning 
request in the KCD is used to position 
the cursor. These bits must 
be 00 or 11- 

2-7 Must be off 
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Bite Bit 

1 Bust be on 

1 a) If en, these attribute specifications 

are to replace the attribute byte 
defined for the field. 

b) If eff, these attribute specifi- 
cations are to be added to the 
attribute byte defined for the field 
(logical OB operation) 

2 Protected 

3 Numeric 

4 High-intensity 

5 Nondisplayable 

6 Detectable {net included in subset) 

7 Premcdified 

Bits 4, 5, and 6 are mutually exclusive. If more than one is set, bit 4 
takes precedence over bits 5 and 6; bit 5 takes precedence over tit 6. 
Note: If a message field is tc be emitted from the device output data, 
the attribute bytes preceding the NOLL character must be binary zeros, 
or the first attribute byte must be a NULL character itself. 

5JJ2ti£le_Fage_Cutput_ Messages 

With KFS, you can easily build a multiple page output message. After 
insertion of such a nessage, the terminal operator can view it, one page 
at a time. He also can go back to the beginning of the message if 
desired. 

In our subset each segment is cne logical page (one IPAGE statement in 
the MCD) and is also one physical page (one DPAGE statement in the DOF) 
or one physical screen cr printer page. 

LFAGZ_Selection: When a message has multiple IPAGEs, the value of a 
special message segment field is used for the selection of the LEAGE 
which will be used for the formatting of that segment. For a detailed 
description see Chapter 3, the COND= parameter of the LPAGE statement. 
If the condition value as specified by the program does not natch any of 
the LPAGE defined values, the last defined LPAGE will be used- 

WF;I2IN(J_A_SIMPLZ_MPP 

The basic flow of a MPP and the message calls used are shown in 
Figure 4-23 and described below. 
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figure 4-23. Easic MPP Flew and Calls 



Lecjen d : 

1. After getting control, the MPF must initialize its working storage, 
as this may contain leftover data from a previously processed 
message (likely frcm another terminal) . This is also a requirement 
fcr reusability. 

2. The MPP retrieves the one input message segment with a GU call 
referencing the I/O-PCB. A blank status code means the message is 
placed by IMS/VS in the SSG-AFEA specified in the call. A QC status 
code means there are nc scie messages in the input gueue. The KEE 
must then return control to IKS/VS. Any other status code is an 
error condition and should be handled by an error code status 
routine. 
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3- The input is validated- This should include: 

• Checking the length of input message 

• Checking the format, value and consistency of input data fields 

This validation should te as complete as possible and be done before 
any data base access. 

4. The data base processing is performed- For data base calls and 
status code handling see the data base calls at the first part of 
this chapter- 

5- Optionally, a CHNG call tc the alternate I/O-PCE is used to set an 
alternate destination. This, for instance, is required to print 
cutput on a 3270 printer terminal- The change call must not be used 
against the I/O-PCE. All ncn blank status codes should fce handled 
by an error code status routine. 

The CHNG call is followed by one or more ISPT calls for message 
output segments to this alternate output terminal. 

Note: Only one CHNG call is allowed per alternate PCB for each 
input message. 

6- The response output message is inserted to the originating LTERM via 
the I/O-PCE. One ISRT call is required for each output message 
segment- Any non-blank status code is an error condition. 

7.. The processing of the current input message is now completed- The 
program should new gc back tc the initialization of its working 
storage and the retrieval of the next input message (if any). 

Note: The first thing IES/VS does after receiving the GU call is 
the synchronization point processing of the previous input message. 
This includes the release of the data base change engueue elements. 
As a consequence, the data base positions of all CB PCBs are 
cleared. So after each message GO ycu should start with data base 
G0(s) to access the data base segments as requested ty the new input 
message. This new input message is almost certainly from another 
user (LIEBK). 

SAKE1E CCECL INC.UIB* «*E 

Listed on the next two pages is a sample COBOL MPP, PE4CNINQ (member 
DFS4CNAM in IMSVS.PRIMESFC) . This program expects a terminal to input 
the customer* s number. It will display the customer name and address. 
It uses the sample formats listed in member OE4CNI01 in INSVS.FBIMESFC. 
Oob //SAMP44 1 can be used for its compilation. The same CCEC1 
programming considerations used for the batch CL/I program apply. See 
COBOL Programming Considerations in the first part of this chapter. 

COECL_Com£ile_0£tions_fcr_MPPs 

Eue to the way IMS/VS loads the MPP, only the following combinations of 
COBOL compile options should be used in our subset: 

• NORES,NCEYMK,NCEND0CE 

• RES,EYNAH,INDJOE 

The first combination is recommended, as the second combination must be 
changed when the IMS/VS program prelcad option is used later. 
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000010 

000020 

000030 

000040 

000050 

000060 

000070 

000030 

000090 

000100 

000110 

000120 

000130 

000140 

000150 

000160 

000170 

000160 

000190 

000200 

000210 

000220 

000230 

0002*0 

000250 

000260 

0CC270 

000230 

0002^0 

0003CO 

000310 

000320 

00C330 

000340 

000350 

000360 

000370 

000380 

000390 

000400 

000410 

000420 

000430 

000440 

000450 

000460* 

C00470 

000430 

000490 

000500* 

000510 

000520 

000530 

0005*0 

000550 

000560 

000570 

000530 



IDENTIFICATION DIVISION. 
PROGRAM-ID . ' PE4CNIN3 ' . 
DATA DIVISION. 
U'CKING-STCRAGE SECTION. 
77 GU PIC X<4) 

77 ISRT PIC X(4) 



01 



01 



VALUE 
VALUE 

'0' . 

'1' . 

VALUE 



•GU' . 
'ISRT' 



77 Ein-SKITCH PIC X VALUE 

83 NO-MCRE-INPUT VALUE 

77 NOT-FOUND-NSG PIC X( 35 > 

'INVALID NUMBER - PLEASE RE-ENTER'. 
77 ERPOPT PIC X(4) VALUE '1 
77 M3DNANE PIC X(8) VALUE 'OE4CNI01' 
77 DAD-CALL PIC X(6) VALUE 'DAD CALL' 

01 INPUT-MESSAGE. 

04 FILLER PIC X(4). 
04 TRANS-CODE PIC X(9). 
04 FEOOGCNR PIC X(6). 
04 FILLER PIC X(60). 



CUT-MESSAGE. 

02 OUT-LL PIC S9(3) COMP VALUE +111. 
02 OUT-ZZ PIC S9(3) COMP VALUE 40. 
02 OUT-DETAILS. 



04 
04 

04 
04 
04 



FE2FCNUM 
FE2PCNAM 
FE2PCADP 
FE2PCCTY 
FE2PCPCD 



02 OUT-F.PPOP 

SE2PCUST. 

04 FE2PCNUM 
FE2PCNAM 
FE2PCAD=> 
FE2PCCTY 
FE2PCTCD 
FILLER 



PIC X(6). 
PIC X(20). 
PIC Xf20). 
PIC X' 20). 
PIC X(6). 
PIC X(35). 



4 

04 
04 
04 
04 



PIC X(6). 
PIC X(20). 
PIC X(20). 
PIC X(20). 
PIC X(6). 
PIC X(40). 



01 CUST0MFP-S3A. 

04 FILLER PIC X(19) VALUE ' SE2PCUST( FE2PCNUM 

04 SSA-CK"JM PIC X(6).. 

04 FILLF.P PIC X VALUE ' )' . 

LINKAGE SECTION. 

PCB FOR INPUT OUTPUT LOGICAL TERMINAL 
01 C1FC. 

02 FILLEP PIC X(10). 

02 C1FCSTAT PIC X( 2 ) . 
PCB FCR CUSTOMER DATABASE 
01 D1PC. 

02 FILLER PIC X(10). 

02 D1PCSTAT PIC X( 2 ) . 

EJECT 

PROCEDURE DIVISION. 

ENTRY 'DLITCBL' USING C1PC, D1PC. 



0000200 
0000300 
0000400 
0000500 
0000600 
0000700 

ooooeoo 

00009CO 
0001000 
0001100 
0001200 
0001300 
00014C0 
0001500 
CCC1600 
0001700 
0001600 
0001900 
0002COO 
0002100 
0002200 
0002300 
0002400 
0002500 
0002600 
00027C0 

oooceoo 

0002^00 
C0C30C0 
0003100 
0003200 
0003*00 
C0C34CO 
00035CO 
0003600 
0003700 
0003000 
0003900 
0004000 
000+100 
CC042C0 
04 30 
0004430 
0004500 
00C';6C0 
0004700 
000^800 
0004900 
0005000 
0005100 
0005200 
0005300 
OC05400 
0005500 
0005600 
0C05700 
0005800 
0005900 
0006000 
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000590 
000600 
000610 
0C0620 
000630 
000640 
000650 
000660 
000670 
000680 
000690 
000700 
000710 
000720 
000730 
000740 
000750 
000760 
000770 
000780 
000790 
0O0GCO 
000810 

ooosco 

00CO30 
000640 
000850 
000860 
000870 

oooeco 

000890 
000900 
000910 
000920 
000930 
000940 
000950 
000960 
000970 
000960 



PERFORM READ-MESSAGE. 

PERFORM PROCESS-MESSAGES UNTIL NO-MORE-INPUT. 

GOBACK. 

READ-MESSAGE. 

CALL 'CBLTDLI' USING GU, C1PC, INPUT-MESSAGE. 
IF C1FC3TAT = ' CC ' 

THEN MOVE ' 1' TO END-SWITCH 
ELSE IF C1PCSTAT NOT = SPACES 
THEN CALL 'OFSOAER' USING 

C1PC, BAD-CALL, INPUT-MESSAGE, ERROPT. 

PROCESS-MESSAGES. 

MOVE FEOCGCNR TO SSA-CNUM. 
PERFOPM PE4D-CU5TCMER-DB 
IF D1PCSTAT = SPACES 

THEN MOVE CORR SE2PCUST TO OUT-DETAILS 

MOVE SPACES TO OUT-ERROR 
ELSE MOVE NOT- FOUND -M50 TO OUT-ERROR 
MOVE SPACES TO OUT-DETAILS. 

PERFORM ISRT-MESSAGE. 

PERFORM READ-MESSAGE. 

READ-CUSTOMER-DB. 

CALL 'CBLTDLI' USING GU, D1FC, SE2PCUST, CUSTOMER-SSA. 
IF D1PCSTAT = SPACES OR 'GE' 
THEN NEXT SENTENCE 

ELSE CALL 'OFSOAER' USING D1PC, BAD-CALL, 
5E2PCUST, EPPOPT. 

ISRT-MESSAGE. 

CALL 'CBLTDLI' USING ISRT, C1PC, OUT-MESSAGE, MODNAME . 
IF C1FCSTAT NOT = SPACES 

THEN CALL 'DFSOAER' USING C1PC, BAD-CALL, 
OUT-MESSAGE, ERROPT. 



0006100 
0006200 
0006300 
0006400 
0006500 
0006600 
0006700 
0006800 
0006900 
0007000 
0007100 
0007200 
0007300 
0007400 
0007500 
0007600 
00077C0 
0007800 
0007900 
0008000 
0003100 
0C0S200 
0006300 
0008400 
000S500 
0C0S600 
0008700 
0008800 
0C08900 
0009000 
0009100 
0009200 
0009300 
0C094C0 
0009500 
0009600 
0009700 
0009600 
0009900 
0010000 



SAMFLE PL/I INQUIRY MEE 

Listed below is a sample PL/I MPP, PE4ENINQ (member DFSUPNAM in 
IMSVS.PEIBESEC) . This program expects a terminal to input the customer 
number- It will display the customer name and address. It uses the 
sample formats cf member OE4CNIC1 in IMSVS.PRIMESFC. Job //SAME451 can 
be used fcr its compilation™ 
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PE4NINQ: PROCEDURE (C1PC_PTR,D1PC_PTR ) OPTIONS (MAIN); 

/« « » E C L A R A T I N 5 » « »/ 

DCL 1 C1PC BASED (C1PC PTR), 
Z FILL CHAR (10), 
Z STAT CHAR (2), 
1 D1FC BASED (D1PC_PTR) LIKE C1PC; 

DCL 1 INPUT_MESSAGE , 

2 FILL1 CHAR (6), 
2 TRANS_CODE CHAR (9), 
2 FEOOGCNR CHAR (6), 
2 FILL2 CHAR (60), 

1 OUT MESSAGE, 

2 OUT_LL INIT (111) FIXED BINARY (31), 
2 OUT ZZ INIT (0) FIXED BINARY (15), 
2 OUT~DETAILS, 

3 FE2FCNUM CHAR (6), 
3 (FE2PCNAM, 
FE2FCADR, 

FE2FCCTY) CHAR (20), 
3 FE2FCFCD CHAR (6), 
2 OUT_ERROR CHAR (35), 

1 SE2FCUST, 

2 CUST_DETAILS LIKE OUT_DETAILS, 
2 FILL CHAR (40), 

1 CUSTCMER_SSA, 

2 FILL1 CH/R (19) INIT ( 'SE2PCUST( FE2PCNUM ='), 

2 SSA CNUM CHAR (6), 

2 FILL2 CHAR (1) IHIT (')'); 

DCL (<GU INIT ( 'GU' ), 

ISRT INIT ( 'ISRT' ), 
ERROPT INIT ( '1' )) CHAR (4), 
(NODNAME INIT ( '0E4CNI01 ' ) , 

BAD CALL INIT ('BAD CALL')) CHAR (8), 
(THREE INIT (3), 
FOUR INIT (4)) FIXED BINARY (3D) STATIC, 
(C1FC PTR.D1PC PTR) POINTER, 
(PLITDLI, DFSOAER OPTIONS (ASSEMBLER)) ENTRY; 



/***PROCESS 
READ MESSAGE: 



MESSAGES***/ 



call plitdli ( three ,gu.c1pc_ptp , input_message ) ; 
if c1pc.stat = •qc then return; 
if c1fc.stat -= ' ' 

then call dfsoaer ( c1pc ,bad_call,input_message , erropt ) ; 

ssa_cnum = feoogcnr; 

/***read customer data base***/ 

call plitdli ( four ,gu,d1pc_ptr .se2pcust ,customer_ssa ) ; 
if d1fc.stat = ' ' then do; 

out_details = cust_detailsj 

out_error = ' ' ; 

endT 
else if d1fc.stat = 'ge* then do! 

out_errcr = 'invalid number - please re-enter'? 

out_oetails = ' ' 5 

END ; 
ELSE CALL DFSOAER ( D1PC,BAD_CALL, SE2PCUST, ERROPT ) ! 

/***INSERT MESSAGE***/ 

CALL PLITDLI ( FOUR , ISRT,C1PC_PTR,0UT_MESSAGE .MODNAME ) J 
IF C1FC.STAT -= ' ' 

THEN CALL DFSOAER ( C1PC,BAD_CALL,0UT_MESSAGE , ERROPT ) 5 

GO TO read_message; 
END pewinq; 



0000010 
0000020 
0000030 
0000040 
0000050 
0000060 
0000070 
0000060 
0000090 
0000100 
0000110 
0000120 
0000130 
0000140 
0000150 
0000160 
0000170 
0000180 
0000190 
0000200 
0000210 
0000220 
0000230 
0000240 
0000250 
0000260 
0000270 
0000280 
0000290 
0000300 
0000310 
0000320 
0000330 
0000340 
0000350 
0000360 
0000370 
0000330 
0000390 
0000400 
0000410 
0000420 
0000430 
0000440 
0000450 
0000460 
0000470 
0000480 
0000490 
0000500 
0000510 
0000520 
0000530 
0000540 
0000550 
0000560 
0000570 
0000560 
0000590 
0000600 
0000610 
0000620 
0000630 
0000640 
0000650 
0000660 
0000670 
0000680 
0000690 
0000700 
0000710 
0000720 
0000730 
0000740 
0000750 
0000760 
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HASD1ING ERROR STATES CCEES 

The handling of errcr status cedes in an MPP is the same as previously 
discussed for a DL/I batch program. Ihe same status code error routine 
can be used- See the section "Status Code Error Routine" earlier in 
this chapter. 

C C N V E R S A TJ N A L_ P R C E S S I N G 

For an introduction to conversational processing, see Chapter 3, "Data 
Communication Design," in the section entitled "Conversational 
Processing." 

RETRIEVING THE SPA AND TERMINAL INPU1 

When an HEP that processes a conversational transaction code receives 
control, the GU call against the I/O PCE retrieves the scratch pad area 
(SEA) . The sucseguent GN call will retrieve the actual input message. 
Data saved in the SEA can be in any form- The GO call for retrieving 
the SPA in COEOL is: 



j CALL »CBL1DLI* USING GU-FUNC,IC-PCB, SEA-AREA. | 

1-- -------------- ------------.------.---.-_--------.j 



In PL/I: 



r ----------- -.....-..-..-.-. ^ 

I CALL PLITCLI |THR EE,GtLFUNC,IO_PCBPTR,SPA_AREA) ; | 
i- -.- — -----...-..- j 



Status_Codes: 

bb: SPA retrieved in working storage field SPA-AREA. 

QCz No mere input transactions; return control to IMS/VS, 

ether: Error situation 

SCRATCHPAD AREA FORKAT 
The SPA format is: 



r ~ 1 

I LL | XXXX | IRAK CCDE | USER WORK AREA | 

L----- -__.----.. .. „ j 

where: 

LL 

is a halfword binary field containing the total number of 
characters in the SPA, including LL, XXXX, TRAN CCDE, and DSER 
WOEK AREA. This field must not be modified by the user- Ihe 
size of all SPAs in cur subset is fixed at 1300 bytes. When 
EL/I is used, the II field must be declared FIXED BINARY (31), 
a binary fullwcrd- The two extra bytes must not be included in 
the LL value. 
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xxxx 

is a U-tyte area reserved for I M£/\S- XXXX must not be 
modified by the user., 

THAN CODE 

is an 8-byte field ccrtaining the trarsaction code that caused 

the program to be scheduled- The transaction code can te frco 

1 to 8 bytes, left- justified, and padded with blanks. 

Note: If the MPP processes both conversational and 
ncn-ccnversational transactions, the TRANCODE should be checked 
after the GU to determine if a GN is reguired. 

USER WORK AREA 

This area is for retaining user information (for example, 
intermediate calculations, data retrieved from the data base, 
or previous input data) reguired by the MPP for processing of 
subseguent input data frcm the same terminal. This area is 
cleared to binary zeros on the initial entry of the 
conversation. 

After the input scratchpad area and input message have been 
obtained, one or more data base calls may be made and one 
output message may be built. The application program may wish 
to retain data entered from the terminal or obtained frcm data 
bases. This data is saved in the user work area portion of the 
scratchpad., 

i§22i!!_Cf .JFA^lser^Kork^Area 

In general, three ditferent categories of data can be stored in the SPA: 

• Conversation control data, used to interrelate the successive input 
messages of a terminal. 

• Input data sawed from previous input messages, not yet stored in the 
data base. 

• Data base information already retrieved in the processing of 
previous input from the terminal. 

The conversational control data is used to keep track of the 
conversation. You should reccrd which input fields were in error, what 
the next expected input would be, etc. 

You must also save data base position information (for example, root-key 
values) as IMS/VS will have cleared the data base position during 
synchronization point processing. This will occur between terminal 
interactions. 

Input data must be saved in the SPA if you don't want to update the data 
base until all input is received and successfully processed. 

Saving data base data in tbe SEA should only be done if doing so would 
save EL/I data base calls during processing of subseguent input messages 
of this terminal. 



Data Base Processing 4- 65 



l££Ui_5§ssage_Fojmat 

From a terminal operator's viewpoint, the format of the input data at 
the terminal is the same as any nonccnversaticnal, transaction -type 
message™ IMS/VS removes the transaction code from the message segment 
and places it in the scratchpad area. The message segment is left 
justified to remove the transaction cods. It is retrieved fcy the GN 
call issued after the GO call that retrieved the scratchpad. The layout 
of the input message segment data processed by MFS is as defined in the 
HIE. 

Note: If the transacticn cede is defined in the MID (as we do) , IMS/VS 
will only remove this transaction code at the first pass. If the sane 
MIE is used for subsequent passes the 9 byte TBANCODE field defined in 
the MID will be present. See sample program FE4C0RDR (member EFS4CNEW 
for COBOL* or DFS4ENEW for FI/I) in IMSVS. PRIMESRC for more details. 

DATA BASE PROCESSING IS CCNVEBS ATIONAL MCEE 

The actual DL/I data base calls fcr a conversational program are exactly 
the same as before. 

Remember, the list's data base position is cleared by IMS/VS 
synchronization pcint prccessing between successive terminal input 
messages (interactions). 

INSERTING THE SEA ANE TF.BRIMU COTEOT 

If the application program modifies or initializes any SPA fields, it 
must return the SPA to IMS/VS before issuing ancther GU or terminating. 
A SPA is returned to IKS/VS by inserting it to the I/O PCB. 

The insert (ISBT) call for CCECI is coded as follows: 



i ------ - - -- -_-- --_- ^ 

| CALL 'CELTDLI 1 OSING ISRT, IO-PCB, SPA-AREA. | 

i---<,--. .----..-.-- _-j 

cr, in FL/I: 

r --------- -. . — ^ 

I CALL PLITELI (TEREE, ISRT_FUNC ,IO_PCBPTR, SPA_AREA) ; | 



Status_Codes: 

bb: Call successful, SEA accepted by IMS/VS. 

other: Error situaticn. 

£ii£E!lt _M ess ajge_Fcr. mat 

A response to the originating terminal is required to allow the 
cenversation to continue- The terminal operator is prevented frcm 
entering more data to fce processed (except IMS/VS commands) until he has 
received this response. 

The output message segment format fcr a conversational application 
program is the same as fcr any nonccnversational output message. 
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T§rj^£a^in2_The_ Condensation 

A conversation may be terminated by the conversational program, terminal 
operator, master terminal operator, or IMS/VS. A conversational program 
terminates a conversation ty: 

• Blanking the transaction code in the SPA and returning the SEA to 
IMS/VS through an ISET call. This terminates the conversation as 
soon as the terminal has received the message response. This is the 
recommended procedure. 

The terminal operator terminates a conversation by: 

• Entering a /EXIT command from the terminal participating in the 
conversation. 

The master terminal operator terminates a conversation by: 

• Entering a /EXIT command which specifies the terminal in 
conversation. 

• Entering a /S18BT IIKE (no PTEBM specified) for the line of a 
terminal in conversation. 

IMS/VS terminates a conversation if, after a successful GU or insertion 
of the SEA, a conversational application program fails to insert a 
message. When this situation occurs, IMS/VS sends the message CFS 32721 
NO RESPONSE, CONVERSATION TERMINATED to the terminal, ends the 
conversation, and completes synchronization point processing. 

When terminating the conversation, IHS/VS deletes the current SEA. If 
the next terminal input message is for a conversational transaction, a 
fresh SPA is made available tc the program. It is recommended that you 
terminate the conversation at each logical end (for example, when an 
order is stored in the data base) of an interactive session. This can 
best be done by the HPP. Because the transaction code is defined in the 
HID, no special terminal operator action is required to restart the same 
conversation (for example, entry of next order) . A transaction code 
password is reguired for each first pass of the conversation if it is a 
password protected transaction. 

jlotes : 

1. You should implement a standard subfuncticn cede (for example, END) 
in a predefined input format field tc allow the terminal operator to 
request the MPP to terminate the conversation. 

2. A help function (for example, HELP) is recommended for complex 
conversations. The MPP could resend the latest message based on SEA 
content together with advice about the next possible action. 

ROLES FCE HBIIING CCNVEBSATICNAI EBCGBAMS 

The following rules should fce observed when writing conversational 
programs within cur subset. 

• The first 6 bytes of the SEA cannot be modified in any way ty the 
application program. (IMS/VS uses these 6 bytes to identify the 
SPA.) 

• Tc terminate a conversation, the transaction code (beginning in 
position 7) should be changed tc blanks. 
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• If modified by an application program, the SPA oust be returned to 
IMS/VS through an ISRT call in order to make the updated SFA 
available during the next interaction of the conversation. 

• The SFA cannot be returned tc IMS/VS more than once (that is, fcr 
every GO call fcr the SPA, there is only one ISRT call for the SPA). 

• One and only one response output message must be inserted to the 
I/C-PCB for each SEA/KSG input. This message can consist of as many 
segments as reguired. 

• Conversational programs must be designed to handle the condition in 
which the first GO call to the I/O-FCE produces no message to 
process. This ccndition can occur if the operator cancels the 
conversation through an /EXIT command, prior to the program issuing 
a GO call, and this was the only message in the gueue to be 
processed. 

WRITING A CCNVEBSATICNAI KFF 

The basic flow of a conversational MPF and the message calls used are 
shewn in Figure 4«24 and described in the following. 
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ISRT CALL(S) FOR OUTPUT MSG 



















Figure 4-24. Conversational HIE Flew and Calls. 

The following notes relate tc the numbers in Figure 4. 24: 

1. After receiving control, the MPP oust initialize its working storage 
as this may contain leftover data from a previously processed 
message (likely f rem accthex terminal) • 

2. The MPP retrieves the SPA with a GU call, referencing the IC-FCE. A 
blank status code means the SEA is placed by IMS/VS in the SPA-AREA 
specified in the call. A QC status code means, there are no more 
messages in the input queue. The MEE must then return control to 
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IMS/VS. Any otber status code is an error condition and should be 
handled by an error code status routine (see "handling Error Status 
Codes" earlier in this chapter). 

3. The actual terminal input is retrieved by a GN call, referencing th€ 
same IC-ECB. A blank status code means the one input message 
segment is placed by IMS/VS in the MSG-AREA specified in the call- 
Any other status code is an error condition. 

4. The input is validated- This should include: 

• Checking the SEA fcr status cf conversation; what was the 
expected irput 

• Checking the length of input message 

• Checking the format, value and consistency of input field using 
conversation ccntrcl information in the SPA. 

This validation should be as complete as possible and be done before 
any data base accesses. 

5. The data base processing is done as before. Cata base elements and 
their update status required for subsequent input message processing 
can be saved in the SEA. 

6. The updated SPA is returned to IMS/VS with a ISRT call. Only a 
blank status cede is acceptable. If the SPA content is of no use in 
the processing of the next terminal input, the conversation should 
be terminated by blanking the transaction code in the SEA before the 
ISRT call. 

7. The response output message is inserted to the originating LTERM via 
the I/O-PCE. One ISRT call is required for each output message 
segment. Any non-blank status code is an error condition. 

8.. Ihe processing cf the current input message is now completed. Ihe 
program shculd new gc back to the initialization of its working 
storage and the retrieval of the next SPA ♦ input message (if any). 

SAKELE CCNVERSA1ICNAI FEES 

Two CCEOL and PL/I ccnversaticral MPPs are included in IMSVS.PRIMESRC: 

• PE4C0RER (member DFSUCNES for COBOI and DFS4ENEW for EI/I) , which 
processes transaction TIUCOEER for the insertion of new customer 
orders into the data base. 

• PE4C0CDEL for COBOL and DFS4PDEL fcr PL/I (member DFS4DEL) , which 
processes transactions 1E4C0DEL and TE4CCCNG for the deletion and 
change, respectively, of customer orders in the data base. 

You should study these programs, especially the way they handle the 
input message, output messages, and the SPA. 

2ISTING_YOUR_MPP 

Testing of a MPP can most efficiently be done in batch mode using a 
terminal simulator program, such as the FDP, Eatch Terminal Simulator 
II, 5796-EGT. 

Fcr mere information see SH20-18U4, "ETS II Program Description And 
Cperation Manual." 
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AECUT THIS ChAPTeF 

This chapter consists cf tbr€€ farts: 

1. Introduces the function of data base reorganization in a DI/I 
environment. It is a first-time introduction into the requirements 
for, and the process cf, data base reorganization. It gives an 
overview of the DI/I utilities for reorganization to be used in the 
subset. 

2. Gives a formal description of the available DL/I utilities for data 
base reorgani2ation- As such, it is the main source of reference 
for the actual use of the utilities. 

3. Introduces the use of the utilities for a particular environment. 
It proceeds along the three phases of our subset sample environment 
from the reorganization cf one data base up to the transition of one 
phase into another- Samples are provided for each function. It 
contains guidelines for the design of ycur own reorganization 
procedures. 

«HAT_IS_EE0EGOIZAIICN 

Reorganization is the process of changing the physical storage and/or 
structure of a data base to better achieve the application's performance 
requirements- He distinguish between the following two types: 

• Physical reorganization , to optimize the physical storage cf the 
data base. 

• Logical reorganization, to optimize the data base structure. 

HHM_20_BigRGANIZE 

Physical reorganization is normally required by one of the following: 

• Degradation in processing program performance due to degraded data 
base storage, that is, the segments belonging to one data base 
record are stored ever excessive Cl/blccks. This is normally shown 
by an increase in the number of physical l/Os per transaction. 
Chapter 9, "Optimization," provides guidelines for monitoring this. 
Additionally, the VSAP catalog contains the number of control 
interval {CI) and control area (CA) splits. This information can be 
printed tdth access method serrices. 

• lack of free space in the data base, caused by (foreseen) large 
quantities of segment inserts. Again, for VSAM, the catalog will 
provide information on this. For HDAK/CSAM the VTOC can be checked 
for the use cf secondary extents. Also, for HDAM, an increase in 
the number of I/Cs per transaction could indicate an BAA (root 
addressable area) which is tec small. 

Note: Should an abnomal termination due to lack of disk space occur 
during normal processing, the standard recovery procedures of Chapter 6, 
"Data Base Becovery," should be used. The allocated space to the 
affected data base must cf course be increased. 
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logical reorganization is normally caused by design changes in the data 
base. In our subset we will address some changes under the topic 
"Applying Structural Changes" later in this chapter. 

THE FREQUENCY 01 REORGANIZATION 

The freguency cf reorganizing is largely dependent on the application 
environment. However bcth VSAM and DL/I contain special facilities to 
minimize the need for reorganization. If the initial allocation of 
space includes sufficient (distributed) free space, the need for 
physical reorganization would normally be quite low (typically once or 
twice a year) - 

S!EPS_IN_B£OPGANIZATICN 

There are three major tteps in reorganization: 

1. Unload the data bases. 

2. Delete the old space, redefine the new space, and optionally change 
OBD parameters (CECGIK). 

3. Restore the data bases. 

Eecause step 2 above deletes the existing data base, it is recommended 
that you make an image copy (see Chapter 6, "Data Base Recovery") just 
before you do the unload. Another method would be to rename the old 
data space and define new data space. The old data space can then be 
deleted after reorganization and subsequent image copies are made. 

You should also make image dumps of all your data bases immediately 
after the reload and before any application program is executed. 

OVJMII!i_2I-3BJ«SIQl§ANIZATION/igAD_ClIIIlIES 

The EL/I reorganization utilities provide three basic functions: 

1. The reorganization of DL/I data bases. 

2. Establishing logical relationship connections when initially loading 
data bases having logical relationships. 

3. Creation of secondary INDEX data base(s) when you load data bases or 
when ycu reorganize them. 

The seven basic utility programs involved in data base 
reorganization/load processing are: 

1. INDEX Reorganization Unload (DFSURDLO) 

2. INDEX Reorganization Reload (DFSURRLO) 

3. HD Reorganization Unload (BFSURGUO) 
4« HD Reorganization Eelcad (DFSURGLO) 

5. Data Ease Prerecrgarizaticn (DFSURPRO) 

6. Data Ease Prefix Resolution (DFSURG10) 

7. Data Ease Prefix Update (DFSORGPO) 
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Of these utilities, there are two types: physical reorganization 
utilities and logical relationship resolution utilities. 

PHYSICAL BEOBGfiNIZAIION UTILITY PROGRAMS 

There are two sets each of two physical reorganization utilities. 

5b§-INDEX_Eeoiaanization_Dtd.lities 

The INDEX Reorganization Onload utility (DFSUEULO) and the corresponding 
INDEX Eeload utility (EFSUBELC) can be used to: 

• Reorganize the primary index data base of a HIDAM data base. 

• Create a secondary index data base. 

• Beorganize a secondary index data base. 

5tS_l?D_Beorganizatign_ Utilities 

The HD Beorganization Unload utility (DFSUSGUO) and the corresponding 
Beload utility (EJSURGLO) can be used to: 

• Beorganize a HDAM, HIDAM, cr SHISAM data base. 

• Create work data sets if the data base being reloaded includes 
logical relationships and/or secondary indexes. 

No t es : 

• The HE utilities should be used fox the unload/reload of a SHISAM 
data base only if this data base is to be converted to a HDAM or 
FIEAM data rase. 

• Use of the HE Unload/Beload utilities in making structural changes 
to a data base is discussed later in this chapter under "Applying 
Structural Changes." 

LCGICAL RELATIONSHIP RESOLUTION UTILITY PECGBAMS 

The following three logical relationship resolution utilities programs 
are required when initial leading or reorganizing data bases with 
logical relationships: (1) Data Base Prerecrganizaticn, (2) Data Base 
Prefix Besolution, and (3) Data Base Prefix Update- 
Da ta_Base_Pre re or^anization_UJ:i^^ 

This utility creates a control data set that is used by other utilities. 
This control data set is needed when initially loading or reorganizing 
data base(s) with logical relationships and/or secondary indexes. 

Da ta_Ba se_ Pref ix_ Be sol ution_ Utility 

This utility combines and sorts all work data sets generated by the HD 
Beload utility or by the initial data base load process. This utility 
generates an output work data set that contains the prefix information 
needed to complete the loading and/or reorganization of data bases which 
contain logical relationships. If secondary indexes are present, a 
separate output data set is also generated, used to build these indexes. 
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£§t§-B§§§_Ili§f!ilL2Edate_utility. 

This utility uses the output data set generated by the Data Base Prefix 
Resolution utility to update the prefix of each segment whose prefix 
information is affected by a data base load and/or reorganization. 

ODIX_JSECBG»NIZmCK_UKIC*D^ 

A flow diagram of the INDEX Reorganization Onload utility is shown in 
Figure 5-1- 
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Figure 5-1. INDEX Reorganization Unload Ctility 



JCL STATEMENTS 

The INDEX Reorganization Unload utility is executed as a standard OS/VS 
job. The following «3CI statements are reguired: 



EXEC 



IKS 
DD 



SY2PRINT 
CD 

SYSIN 
ED 



This statement must be in the form: 

PGM-DFSRRC00,EAEM-»ULO,EFSURUL0» 

Defines the library containing the DBD that describes 
the data base to be reorganized (that is, 

DSN=IMSVS.DBDLIB,DISP=SHR) . This data set must reside on a 
direct access device. 

Eefines the output message and statistics data set. 
Eefines the input control statement data set. 
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vsamin 
DD 



dataout 
DD 



indexwrk 
DD 



DESVSAMP 
EE 



Defines the VSAM KSDS data set to be reorganized. 
The ddname must be the sate as the name in the DBD that 
describes this data set. It east also appear on the 
utility control statement in the SYSIN data set of this 
jot step. 

Defines the reorganized output data set. It can be 
any name, but the name must appear in the associated 
utility ccntrcl statement. The data set must reside on 
either tape or a direct access device. 

This seguential data set is blocked to the blocksize of 
the output device, up to a maximum of 16K. Since the 
blocking factor is determined at execution time, standard 
labels must be used on all output volumes. 

Describes the output data set (DFSURIDX) from the 
Prefix Resolution program which contains secondary index 
information. This statement is required if the utility 
control statement is type "X"; otherwise, it is optional. 
The ddname must be the same as the name starting in 
position UO of the control statement. 

Eescribes the data set that contains the buffer 
information required by the DI/I Buffer Handler. This DE 
statement is required. (For additional information, see 
"Defining the IMS/VS Data Base Buffer Subpools" in 
Chapter 1.) 



UTILITY CONTFOL STATEMENT 



i 2 a 



13 



UO 



50 



80 



B 1 dbdname vsanin datacut 
X ddname ddnane 



indexwrk [comments] 
ddname 



Position 



13 



22 



Description 

This must be either 'F* or 'X'. An •R* should be coded if 
this is a separate reorganization of an existing INDEX 
data base. An 'X' should be coded if this is the creation 
of an INDEX data base, that is, if the VSAM KSDS is 
"empty. " 

This must be a 1, There is nc default, and if this field 
is left blank an error message is generated. 

This must be the name of the DBD that includes the KSDS to 
be reorganized. 

This must be the ddname of the KSDS to be reorganized. It 
must appear in the referenced DBD, and a corresponding DE 
statement must have been provided. 

This must be the ddname of the output data set. A 
corresponding DD statement oust have been provided. 
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40 Ihis trust be the ddname of the secondary index work data 
set if rhis control statement is type "X'». 

50 Comments can be placed in positions 50 through 80. 

Note: All other positions must be blank- 

BETUBN CODES 

This program returns cedes preceded (in the case of errors) by numbered 
messages to the SYS-FBINT data set which more fully explain the results 
of program execution. The return codes are as follows: 

All reguested operations have successfully completed. 

4 One or more operations have not successfully completed. 

8 Severe errors have occurred causing job termination. 

12 A combination of error codes 4 and 8 has occurred. 

OOTPtJl MESSAGES AND STATISTICS 

The INDEX Beorganization Unload utility provides messages and statistics 
on data base content for each data set. In addition, it provides an 
audit trail capability. 

EXAMFLE 

A discussion cf the use cf tiiis utility, together with an example, can 
be found under the topics "Beorganizing an INDEX Data Ease" and "Initial 
Data Base Load Processing" later in this chapter- 

A flew diagram of the IlLIX Reorganization Beload utility is shown in 
Figure 5-2. 
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Figure 5-2- INDEX Reorganization Beload Utility 



JCL STATEMENTS 

The INDEX Reogranizaticn Reload utility is executed as a standard OS/VS 
job. A JOB statement (defined by the using installation), an EXEC 
statement, and DD statements that define inputs and outputs are 
required. 



EX1C 



IMS 

DD 



SYSPEINT 
DD 

DFSUIN01 
DD 

vsamout 
DD 



DFSVSAMF 

DD 



This statement oust be in the form: 

FGMsDFSRKCCCPAHM-^LD^DFSOBELO' 

Defines the library containing the EED which describes 
The data base being reorganized. This data set must 
reside on a direct access device. 

refines the output message and statistics data set. 



Defines the unloaded input data set. This data set 
must be created by DFSUEULO. 

Defines the KSDS output data set to be reloaded. The 
ddname must be the same as the name in the DED that was 
referenced when this data set was unloaded. 

Describes th€ data set that contains the buffer 
information required by the DL/I Buffer Handler. This DD 
statement is required- (For additional information, see 
"Defining the IMS/VS Data Base Buffer Subpools" in 
Chapter 1, "Installing IMS/VS.") 
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Not es No SYSIN DD statement or utility control statements are required 
for this utility- 

BETORN COEES 

The following return cedes are provided at program termination: 

Code H§§Bin.9 

All operations have successfully completed. 

H Cne or more warning messages issued. 

8 Cne or more operations have not completed successfully. 

16 Severe errors have occurred causing program termination. 

001POT MESSAGES AKC STATISTICS 

The INDEX Beorganization Feload utility provides messages, statistics 
and an audit trail for the data set being reloaded. 

EXAMPLE 

A discussion of the use of this utility, together with an example can be 
found under the topics "Reorganizing an INDEX Data Base" and "Initial 
lata Ease Load Processing" later in this chapter. 

The ¥.1 Reorganization Onload utility can be used to unload an HDAM, 
HIDAM, or SHISAM data base to a CJ5AM formatted data set. There are no 
utility control statements for this utility. 

A flow diagram of the HD Reorganization Onload utility is shown in 
Figure 5-3. 
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Figure 5-3. HD Eeorganization Onload Otility 



JCL STATEMENTS 

The HD Reorganization Onload utility is executed as a standard CS/VS 
jot. The following JCL statements are required. 



EXEC 



IMS 
ED 



SYSPBINT 
CD 

DFS0RGU1 
ED 



data base 
DD 



This statement must be in the following form: 

PG^DFSBFCOOfFABft^'OLOfDFSOBGOO, dbdname* 

where the paratceters 0L0 and EFSORGOO describe the utility 
region, and dfcdname is the name of the DED which describes 
the data base to be reorganized. 

Defines the library (IMSVS. EEELIB) containing the DBD 
which describes the data base to be reorganized. This 
data set must reside on a direct access device. 

Defines the lessage and statistics output data set. 



Defines the sequential, variable blocked output data set. 
This DD stateient Bust be supplied. 

The data set can reside on either tape or a direct access 
device. Since output is blocked to the maximum size the 
output device can handle, up to 8K, standard labels must 
be used on output volumes. Standard labels must be used 
on output volumes. 

Defines the data base data set to be reorganized. 
The ddname must match the ddname in the DED. 
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If this is a HIDAM data base, you must also include a DD 
statement fcr the primary index. That DD name must be the 
same as specified in the primary INCEX DBD. Nc DD 
statements are required for any secondary indexes 
associated with this data base, JCL must be included for 
all lcgically related data bases, even though these data 
bases are not unloaded. 

This data set must reside en a direct access device. 

DFSVSAMP Eescribes the data set that contains the buffer pool 
DD information required by the DL/I Buffer Handler- This DD 

statement is required. (Fcr additional information, see 
"Defining the IMS/VS Data Ease Buffer Subpools" in 
Chapter 7 , "Installing IMS/VS.") 

BETUBN CODES 

The following return codes are provided at program termination: 

Code 5f3iii£S 

Data base unload successful. 

U Cne or mere warning messages issued. 

8 Severe errcr has occurred. 

12 Multiple warning and/or error messages issued. 

16 Lata base unload not successful. 

OUTPUT MESSAGES AND STATISTICS 

The HD Eecrganization Unload utility provides output messages and 
statistics. An example cf the messages and statistics obtained from this 
utility, accompanied by explanatory infermation, is provided in Chapter 
3 cf the IMS^VS Primer Samjale listings manual. 

EXAMPLE 

A discussion of the use cf this utility, together with an example, can 
be fcund under the topic "Reorganizing a HDAM or HIDAM Data Ease" later 
in this chapter. 

The HE Fecrganization Eeload utility can be used to: (a) relcad an HDAM 
or HIDAM data base frcm a data set created by the HD Unload utility, and 
(b) create work data sets (if the data base to be reloaded includes 
logical relationships or secendary indexes) which are to be used as 
input to the logical relationship resolution utilities. 

A flow diagram of the HE Beorganization Beload utility is shewn in 
Figure 5-U. 



5.10 IMS/VS Erimer 



/ WORK \ 
( DATA 




DATA 

BASE 

DATA 

SET 



HD 
REORGANIZA- 
TION RELOAD 
DFSURGLO 




DATA 

BASE 

DATA 

SET 




INPUT 

CONTROL 

STATMENTS 



OUTPUT MESS 
AGES AND 
STATISTICS 



INDEX 
DATA 
SETS 



Figure 5-4. HP reorganization Feload Utility 



JCL S3A1EMENTS 

The HE Reorganization Reload utility is executed as a standard OS/VS 
jcb. The following JCL statements are required. 



EXEC 



IM! 
DD 



SYSFEINS 
ED 

DFS01NP1 
ED 



EFS0RWF1 
ED 



This statement must be in the form: 

FGK=DFS5fC00,FA5K=•ULU,DFS0PGL0 r dbdname• 

where dbdname is the name of the DEE which includes the 
data base tc te relcaded. 

Describes the litrary containing the DED referenced 
in the EXEC statement FARM field (normally this is 
IMSVS.DBDLIB) • This data set must reside on a direct 
access device. 

Defines the iressage output data set. 



Describes the input data set .containing the data to 
fce relcaded- This is the data set created by the HD 
Recrganizaticn Unload utility. The data set must reside 
either on tape or a direct access device. 

Describes tb€ data set to be created during reload 
that will be used as input by the Prefix Resolution 
utility 1DFSURG10) to resolve logical or secondary index 
relationships. This DD statement must always be present. 
It can specify DE DDMMY if the data base is net involved 
in logical relationships or secondary indexes. 
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The DCB parameters for the DD statement must include 
1RECL=300, SECEM=VE, and ELKSIZE specified to be the same 
as that specified for the work data set of the user's 
initial load program- A full track blocksize or 8-16K for 
tape is recommended. 

Ihe data set Bust reside either on tape or a direct access 
device. 

database Defines the data base data set to be reorganized. 

EE One statement cf this type must be present for each data 

set that appears in the EEC which describes this data 
base. The ddname must match the ddname in the EEE. 

If this is a BIDAM data base, a DD statement must also be 
included for the KSDS of the primary index. This ddname 
is specified in the DBD for the index data base. No ED 
statements are required for any secondary indexes 
associated with this data base. 

This data set must reside on a direct access device. 

DFSOBCDS Defines the control data set for this program. This 

EE data set must be created by the Pre reorganization utility 

(DFSURPRO) . This DD statement must be included if logical 

relationships exist. 

This data set must reside en either tape or a direct 
access device. 

DFSVSAMP Describes the data set that contains the buffer pool 
DD information required by the DL/I Euffer Handler. Shis DD 

stateirent is required. (For additional information, see 
"Defining the IMS/VS Data Ease Buffer Subpools" in 
Chapter 7, "Installing IMS/VS.") 

BEIOBN CODES 

The following return codes are provided at program termination: 

Data base relcad successful. 
16 Data base reload unsuccessful. 

OUTPUT MESSAGES AND STATISTICS 

The HD Beorganization Reload utility provides output messages and 
statistics. An example of the messages and statistics obtained frcm this 
utility, is provided in Chapter 3 of the IMS/VS Primer Sam£le listings. 

EXAMPLE 

A discussion of the use of this utility, together with an example can be 
found under the topic "Becrganizing a HDAM or HIDAM Data Base," later in 
this chapter. 
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The Eata Ease Prereorganizaticn utility creates a control data set that 
is used by the ether logical relationship resolution utilities. This 
utility must be executed before you initially load or reorganize any 
data base which contains logical relationships and/or secondary indexes. 

The input to this utility is a data set which consists of the utility 
control statements that name the data base(s) being loaded and/or 
reorganized. The DEDs that are used for the data bases named on these 
statements must define each data base as it is to exist after the 
logical relationships and/or secondary indexes are established. These 
DBEs must not be modified <jntil the Prefix Update utility has been 
successfully executed. 

The output is a control data set that is used by the HD Reorganization 
Eeload and by the Data Base Prefix Resolution utilities. It is also 
used during the initial load of data bases with logical relationships 
and/or secondary indexes. 

A flew diagram of the Eata Base Prereorganization utility is shown in 
Figure 5-5. 
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Figure 5-5. Eata Base Prereorganizaticn Utility 



JCL S1A1EMEN1S 

The lata Base Prereorganization utility is executed as a standard OS/VS 
job. A JCB statement (defined by the using installation) , an EXEC 
statement, and DE statements that define inputs and outputs are 
required. 



EXEC 



IMS 

ED 



This statement must be in the form: 

FGM=DFSRRCCC,PARM= , ULU r DFSOBPB0• 

Defines the library containing the EBDs which describe 
the data bases named on the input control statements. 
This DE statement must always be included. The data set 
must reside en a direct access device. 
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SYSIN Ihis data set will contain input control statements. 

DD DCB parameters specified within this program are BECFM-FB 

and IFECI=80. ELKSIZE must be provided on this DD 
statement. If BIKSIZE is net specified, there is no 
default and the results are unpredictable. 

SYSP8INT Eefine the iressage output data set. 

E£ Ihe DCB parameters specified within this program are 

EECFM=FE and 1BECL-120. ELKSIZE must fce provided en this 
ED statement. If BLKSIZE is not specified, there is no 
default and the rerults are unpredictable. 

EFSUFCES Defines the output data set for this program. This 
DD data set is the control data set used by subsequent 

utilities. This ED statement must always fce included. 

DCB parameters specified within this program are RECFM=FB 
and LPECL=16CC. BLKSIZE must be provided on this EE 
statement. 

UTILITY CONTBCI STA12KESTS 

1 80 

r _- .------.«._ _,---.-« .--..-..-..-*,...... «. . ----| 

I ! 

! EEIL=database namel , database name2,-.. [comments] | 

! I 



This utility control statement names data bases to fce initially, loaded. 
One or more of these statements can be provided. Each DBD name must be 
left- justified to provide a total length of 3 characters. If the DED 
name is less than 8 characters, sufficient trailing blank characters 
must be provided to make a tctal of 8 characters. A blank must follow 
the last entry on each statement. If a HIDAM data base is tc be 
initially loaded, only its DBD name should be listed on a DEII control 
statement. Neither the HIDAK primary index nor any secondary index DBD 
names should be listed. 

1 SO 

T -------------------------------------------------------------- -., 

I ! 

| DBR=database name 1, database name2,... [comments] | 

I ! 



This utility control statement names data bases to be reorganized. One 
or mere of these statements can be provided. Each DBD name Bust be 
left- justified to provide a tctal length cf 8 characters. If the DBD 
name is less than 8 characters, sufficient trailing blank characters 
oust be provided to make a total of 8 characters. A blank must fellow 
the last entry en each statement. 

If a HIDAM data base is to be reorganized, only its EBD name should be 
listed on a EEB control statement. (Neither the HIDAM primary index nor 
secondary index DBE naoes should be listed.) 
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1 80 

r " * * ---- ., 

I ! 

! OPTIONS^ INCPBNCh,STflT,SU*n J 



L- 



This utility control statement fust be coded as shewn above in our 
subset- It directs the prefix resolution utility to provide statistics 
on the number cf segments being updated and the number of logical 
parents without logical children- 

RETURN CODES 

The following return cedes are provided at program termination: 

Code UsaniJSS 

No errors detected, 

8 One or more error messages have been issued. 

OUTPUT MESSAGES 

The output messages issued by this utility indicate the data base 
operations that must be perfcrired prior to execution of the Prefix 
Resolution and the Prefix Update utilities- For instance: 

* Data bases listed after the characters EEIL= in message DFS861I must 
be initially leaded. 

* Data bases listed after the characters DBR= in message DFS86 1I must 
be reorganized using- the HE Beorganizat ion Unload/Reload utilities. 

* Data bases listed after the characters EES= in message DFS862I must 
be specified en a EBR= ccntrcl card, and the utility must be 
re-executed. If this occurs f you may have omitted a data base to be 
reorganized. 

The Data Base Prefix Resolution utility accumulates the information 
generated on work data sets during the lead and/or reorganization of one 
or more data bases. It produces an output data set that contains the 
prefix information needed to complete the logical relationships defined 
for the data base(s) and, optionally, an output data set containing 
information needed to lre)create secondary index data bases. There are 
no utility control statements for this utility. 

RESTRICTIONS 

The Data Ease Prefix Resolution utility uses the OS/VS Sort/Merge 
programs. Since the maximum sort field permitted by Sort/Merge is 256 
characters, certain limits must be observed. The following restrictions 
apply in our subset: 

1. For any given logical parent/logical child pair, the sum of items a 
and b below must not exceed 200 characters (the balance of 56 
characters is used by IMS/VS for control purposes) : 

a. The length of the logical parentis concatenated key. 
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b. The length of the sequence field of the logical child as seen 
ty its logical parent, 

2. The sum must be computed once for the logical parent and once for 
the logical child- These summations are treated separately. 

The Data Ease Frerecrgaiizaticn utility performs the above limit check 
fcr logical parent/logical child combinations affected by an intended 
data base initial lead or relonad. It should be noted that the limit 
check is a worst-case check. If the limit check fails for a logical 
parent/logical cnild comfcinaxion, message DFS885 will fce issued. Refer 
to the IHS^VS Messages and Cedes Reference Manual for an explanation of 
the message. 

A flow diagram of the Data Base Prefix Resolution utility is shown in 
Figure 5-6. 




Figure 5-6. Data Base Prefix Pesoluticn Utility 



JCL STATEMENTS 

The Data Ease Erefix Resolution utility is executed as a standard OS/VS 
jot.. A JOE statement (defined by the using installation) , an EXEC 
statement, and CD statements that define inputs and outputs are 
required. 



EXEC 



This statement must be of the form: 

PGK=DESUEG 10, EABM= 'options' 

Since this prcgram invokes the operating system Sort, 
program efficiency can be improved by increasing the 
partiticn/regicn size. 
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Th€ PARK field can be used to specify options for the 
SCEl/HEEGE program- A recommended option is 

PABM=«SIZE=En» 

n is the estimated number of records to be sorted. 
Specification of this parameter improves significantly the 
SOBT/MEBGE performance. Guidelines for calculating the 
number of SCBT/MEBGE input records are provided under the 
topic "Hcrk Eata Set Allccaticn' 1 later in this chapter- 



SYSPRINT 
DD 



Defines the lessage output data set for this program. 



ECE parateters specified within this program are RECFM^FB 
and LRECL=12C. BLKSIZE must be provided on the SYStEINT 
DC statement and must be a multiple of 120. 

SYSOUl Defines the message output data set for Sort/Herge- 
EE 

SOBTLIB Defines a data set containing load modules for the 
DD operating system Sort/Merge program. This DP statement 

must always be included. 

SCETWKnn Defines intermediate storage data sets for the 

DD operating system Sort/Merge program. Eefer to the 

appropriate operating system Sort/Merge manual regarding 
specification cf cumber and size of intermediate storage 
data sets. These DD statement (s) must be included. 

SOBTIK Defines the input data set for this program. This DD 
DD statement must always be included. It is referenced by 

the operating system Sort/Merge program and must conform 
to its JCL requirements. The data set(s) referenced by 
this DD statement must be the output work data set (s) 
produced during a data base initial load or reload 
operation; those work data sets must be concatenated to 
form the SOBTIN data set. 

DCE parameters specified within this program are BECIM=VE 
and LRECI=300. The BLKSIZE must be the same as that 
specified for the work data sets (HFls) written during 
initial data base load, or data base reload. 

DFSCBWF2 Defines an intermediate sort work data set. This DD 
CD statement oust always be included. The data set can 

reside on a tape or direct access device. The size ot the 
data set will be approximately the same as that of the 
input data set defined by the SOBTIN CC statement. 

DCE paraneters specified within this program are RECFM=VB 
and LBEC1=3CQ. BLKSIZE must be provided on this CC 
statement. If ELKSIZE is not specified, there is no 
default and the results are unpredictable. 

DFSURWF3 The output data set defined by this statement will 
DD be supplied as input to the Prefix Update utility- This 

statement must always be included™ The data set can 
reside on tape or direct access device. Its size will be 
approximately the same as that of the input data set 
defined by the SORTIU DD statement. 
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DFSURCDS 
ED 



DFSURIDX 
DD 



DCB parameters specified within this program are BECFM-VE 
and IBECI=300. ELKSIZE must be provided on the DFSOEWF3 
DD statement. If BLKSIZE is not specified, there is no 
default and the results are unpredictable. 

Defines the control data set for this program. It 
must te the output control data sets generated by the 
Erereorianization utility. This DD statement must always 
be included. 

Defines an output work data set which will be used if 
secondary indexes are present in the DBDs being 
reorganized/leaded. All notes on DFSURWF3, above, apply to 
this data set also. This data set must be used as input 
to the INDEX Unload program (DFSURUIO) for (re) creating 
secondary indexes. This DD statement is required only if 
secondary indexes are present. 



EETOBN CODES 

The following return codes are provided at program termination: 

Code leaning 

No errors detected. 

4 Returned when either one or both of the following messages 

have fceen issued during program execution: 

EFS678, DFS665 

8 Returned when one or more of the following messages has 
teen issued during program execution: 

EFSS52, DFS655, DFS857, DFS876, DFS877, EFS879, 
rSF880, EIS881 



12 



16 



cr if no data is written to the WF3 data set. 

Returned when either one or both of the messages listed 
under return code 4 and any one or more of the nessages 
listed under return code 8 have been issued. 

Returned ty OS/VS Sort/Herge program. This return code 
takes precedence over the above return codes. 



Note: For return cedes larger than 16, the same meaning stated above 
for return code 16 applies. 
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OUTPUT MESSAGES ANE STATISTICS 

If nc errors are detected by this program, statistics and a norcal 
program termination message will b€ printed. 

DA1A-1ASE_P1IFI2_UPEATJ_UTIIITY_JEFS0BGP01 

The Data Base Prefix Update utility uses the output generated ty the 
Prefix Resolution utility tc update the prefix of each segment whose 
prefix information was affected by a data base load and/or 
reorganization. 

The output of the Prefix Resolution utility consists of one or more 
update records tc Jbe applied to each segment that contains logical 
relationship prefix information. The update records have been sorted 
into data case anc secnent physical location order by the Prefix 
Resolution utility. 

A flow diagram of the Eata Ease Prefix Update utility is shewn ir. 
Figure 5-7. 
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Figure 5-7. Data Ease Prefix Update Utility 



JCL STATEMENTS 

The Data Ease Prefix Update utility is executed as a standard OS/VS job. 
A JOB statement, an EXEC statement, and DD statements that define inputs 
and outputs are reguired. 



EXEC 



This statement must be in the form 
PGK=DFSRBCOO r PARM=»ULU,DFSUEGPO» 
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IMS Defines the library containing the DBDs which describe 

ED the data case |s) that were loaded and/or reorganized. 

This CD statement must always be included. The data set 

must reside on a direct access device. 

SYSPBINT Defines the output message data set. 
DD 

ECB parameters supplied by the program are RECFM=FB and 
LRECL=12C. BLKSIZE must be specified on this EE statement 
and must be a multiple of 120. If BLKSIZE is not 
specified, there is no default and the results are 
unpredictable. 

DFSURHF3 Defines the input work data set for this program- 

EE It must be the output data set generated by the Frefix 

Eesolution utility. The data set can reside on a tape or 
direct access device. This DD statement must always be 
included. 

database References the data base(s) that were initially leaded 
ED and/or reorganized. One DD statement must be present for 

each data set of a data base that has logical 
relationships. The ddname must match the DEKfifE indicated 
in the DEE. If an HIDAM data base is operated upon with 
this utility, a DD statement must also be supplied for the 
KSDS of its primary index data base. 

This data set must reside on a direct access device. 

DFSVSAMP Eescribes the data set that contains the buffer 
DD information required by the DL/I Buffer Handler. This DD 

statement is reguired. (For additional information, see 
"Defining the IMS/VS Data Ease Euffer Subpcols" in Chapter 
7, "Installing IMS/VS.") 

REIUBN CCEES 

The following return cedes are provided at program termination. 

Code Uiafiii23 

No errors detected. 

6 Gne or more error messages issued. The messages contain 
details of the error (s) and are printed as part of the 
system output. 

OUTPUT MESSAGES 

If no errors are detected by this program, the only output message 
issued will be a normal program termination message that indicates the 
number of records processed. 

PHYSIC AL_REORGANIZAJION 

REORGANIZING AN INDEX DATA EASE 

The steps to be taken fcr the physical reorganization of a primary or a 
secondary index data base are the same. 
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Ste.E_.1j Unlca<iLthe_Eata_Ease_ 

Job //SAMP26"? in IMSVS.PRIHEJCB shows an example cf how to do this. 
This jcb Mill unload the primary index of the sample CUSTOMER ORDER data 
base. 

Step.__i_ Chan < gj_Phisical_ParaB€t€f s_ 

Using access method services, the KSDS cluster must be deleted and 
redefined. Only the following physical attributes can be changed before 
the reload: 

• The amount of EASD space: via access method services EEFIKE. 

• The CI size: via the SIZE parameter in the CEE and access method 
services EIEINE. 

H2-5- * f th€ CI SIZE is changed, a DBDGEN cf the altered data base must 
be executed here. 

Ste£_Ji R§!oad_the_I)ata_B.ase_ 

Job //SAMP286 in IMSVS.PBIWEJOB shows an example. This job will reload 
the primary index of the sample Customer Order data base. The jcb alsc 
includes the necessary access method services delete and define 
commands. 

REORGANIZING A HEAM 06 HIEHf EATA EASE 

The 3 basic steps in reorganizing a HDAH cr HIDAM data base are: 

St§2_J[: 2SlSS^.*h€_pata_Ease_ 

Job //SAMP185 in IWSVS.PRIKEJCE shows an example of how to dc this. 
This job will unlcad the phase 1 Parts data base, EE1PARTS. 

§iSE-ii Chanaj5_Phisical_Par > ameters_ 

The following physical parameters can be changed before the relcad: 

• The amount of EASE space: access method services or JCL. 

• The CI size: SIZE parameter in D8D and access method services 

DEEINE. 

• Size of the root addressable area and/or number of root anchor 
points (HDAH cnly). 

Ste__3_ Belcad_the_Data_E.as.e_ 

Job //SAHP186 in IHSVS.PRItEJCE shows the reload of the phase 1 Parts 
data base. 

Note: In addition, several structural changes in the data base can be 
made. See "Applying Structural Changes" later in this chapter. 
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INDICATIONS THAT DATABASES KAY NEED REORGANIZATION 

To determine the need fcr data base reorganization, certain indicators 
shculd be monitored. These indicators are different for CSAM data bases 
and for VSAM data bases. 

In our subset, HIDAB, SHISAM and INDEX data bases will always be VSAM. 
HDAM data bases may be VSAM cr OSAM. As GSAK data bases are never 
reorganized, we are not concerned about them here. 

For each access method JVSAE, CSAM) there are two sources of information 
which can signal the need tc recrganize: 

• The DASD volume table of contents or VSAM catalog data, which does 
not relate to a specific execution of a job, and 

• The buffer pcol statistics that do relate to execution of a specific 
job. 

2SAM_Data_Eases_;2_JiJDAM.£i3li) 

The VTOC of the DASD volume on which an CSAM data base resides may be 
retrieved by the CS/VS utility IEHLIST, with a control record as in the 
following example fcr the phase 1 PARTS data base: 

LISTVTOC FORMAT, V0L=323C=IMSPRM,DSNAKE=IMSFFIME.DE1FAHTS. CEASE 

A growth in the number cf extents (the field identified by "NO EXT") may 
indicate that a reorganizaticn is needed. Typically an OSAM data set 
has only one extent. The message about the number of empty cylinders 
and tracks in this dataset is not necessarily accurate for a data base, 
so it should be ignored. 

The buffer pool statistics obtained by the use of sample routine EFSOAST 
and printed on EE statement //EOOASTA, also provides indicators if well 
monitored. Chapter 9, "Optimization," provides more guidelines for 
this. 

yjsAM_pata_ Eases 

Statistical data about VSAE clusters is maintained in the VSAM catalog 
and is available by running VSAM*s Access Method Services with a control 
card such as the following for the phase 2 Customer Orders data base: 

LISICAT CICSTER All EKTEIES (IMSFEIME. EE2PCUST. CEASE) 

The major indicators can be found in the DATA portion of the cluster, 
under the STATISTICS heading. The RECORDS DELETED and INSEFTEE fields 
contain counts of this activity from the last creation (initial lead or 
reorganizaticn) of this data base. A large number, relative to data 
base size, in either or both fields may indicate a need for 
reorganizaticn. 

Mere important are the SPLITS counts for CA and CI. Control Area (CA) 
splits indicate that significant space is being claimed and that it is 
reorganizaticn time. Control Interval (CI) splits indicate the same, 
but to a somewhat lesser extent. The NUMBER of EXTENTS should net grow. 
If they do, reorganize. 

There is one ether field, applicable to both the DATA and INEEX portions 
cf a cluster, that Kill vary with the number of EXTENTS. This field, 
called TOTAL EYTES IN DATASET, indicates the number of free bytes left 
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in the DA1A or INDEX portion. As this freespace approaches zero, you 
are approaching the requirement fcr a new extent and you should consider 
reorganizing. 

The buffer pool for VSAM is organized into subpools, with one sutpccl 
for each control interval size- In our examples, we have used 1024 byte 
and 2046 byte CI sizes, thus we have two subpools- These were defined 
in each job by the //DFSVSAMP DD statement. 

These statistics are obtained during the execution of a job by calling 
the sample routine DFSOAST, and are listed on the D00ASTA CD statement. 
Two sets of statistics will be listed in our sample — one for each 
subpocl. A detailed discussion of these statistics and their 
interpretation can be found in Chapter 9, "Optimization." 

In the BIDAM organization, the primary INDEX data base can be 
recrgani2ed separately from the main HIDAM data base. (See jobs 
//SAMP287 and //SAMP286 in IMSVS. PRIME JOB.) Because this is normally a 
small data space, you can do this weekly or even daily. 

INITIAL^DAlA^BASE.LCAp.PECClSJIKG 

The initial load of a physical data base which dees not contain logical 
relationships cr secondary indexes is discussed In Chapter 4 under the 
topic "Loading a Data Base." Ncne cf the utilities of this chapter is 
required to lead a single physical data base, which does not contain any 
logical relationships cr secondary indexes. 

LOADING DA1A EASES WITH 1CGICAI RELATIONSHIPS 

Whenever you are leading cne cr mere data bases which contain logical 
relationships, ycu must use the logical relationship resolution 
utilities. Ihis is necessary because, when loading a logical child 
segment, the logical parent segment may net have been loaded, and vice 
versa. So DL/I cannot make the pointer connection at that time. 
Therefore, when loading a legical child cr legical parent, DL/I will 
(automatically) *rite a control record to a workfile (DFSURWF1). This 
workfile is later sorted and used in a prefix update utility. Exactly 
which control records need tc be generated is established beforehand by 
the prerecrgani2ation utility. Figure 5-8 gives an overview of this 
process. 

No t es : 

1. The job for loading the data base must contain DE statements with 
the ddnames cf DFS0BWF1 and EFSUBCDS. The DFSURWF1 DD statement 
describes a data set which is automatically created by IMS as the 
result of the user § s ISBT calls to DL/I at initial load. The DCE 
parameters fcr this statement must include LRICL = 300, RECFM=VB, and 
BLKS1ZE specified to be the same as that specified for any other 
WF1. A basic recommendation is full track blocksize or 8-16K for 
tape. 

2. When loading 2 or more logically related data bases, the DFSUBWF1 
files must be concatenated. This concatenated data set (including 
all created Wfl's) must be specifed to the Prefix Resolution utility 
as input. 

3. The EFSUBCDS DD statement must reference the control data set 
created by the prerecrganization utility. 



Data Ease Reorganization/Load Processing 5.23 



CONTROL 
CARD 



PREREORG 
(DFSURPRO) 



REPORT 




PREFIX 
RESOLUTION 

(DFSURG10) 



ONLY IF LOGICAL 
RELATIONSHIPS 




DFSURIDX 
DFSURWF2 
DFSURWF3 



PREFIX 
UPDATE 

(DFSURGPO) 




"EMPTY" 
SECOND- 
ARY 
INDEX 
DATA 
BASE 



INDEX 
UNLOAD 

(DFSURULO) 




REPORT 



UNLOADED 

INDEX 

DATA 

BASE 



INDEX 
RELOAD 

(DFSURRLO) 




SECOND- 
ARY 
INDEX 
DATA 
BASE 



J L 



Figure 5-8. Initial Data Base load with Logical Relationships 
and/or Secondary Indexes 

Job //SAME270 in IMSVS. EBIMEJCE can be used for loading the Level 2 
Farts and Customer Orders data bases. 
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LOADING DATA EASIS WITK SECONDARY INDEXES 

When initially leading a data tase with one or more secondary indexes, 
you must use the logical relationship resolution utilities- Th€ basic 
process is the sense as th€ cue fci loading data bases with logical 
relationships (see Figure 5-3). 

However, seme additions are reguired: 

1- The prefix resolution utility (DFSURG10) creates an index workfile. 

Its ddname is DfSCFIDX. 

2. The above workfile must be used as input for the index unload 
utility, DFSCROIO. 

Note: The unload nust be dene from a newly allocated, empty KSDS. 

3. The secondary index data base must he reloaded using the Index 
Reload utility. 

Example 

Job //SAMP37C in IMSVS.PRIMEJOB can be used for the initial load of the 
sairpie phase 3 data bases, including both logical relationships and 
secondary indexes. 

WOFK DATA SIT ALLOCATION 

The following guidelines should be observed for a good performance cf 
the data base load process, especially fcr large data bases: 

1. For the initial data tase load job, the input file, the data base 
data set, and the workfile 1 should be on separate volumes. 

2.. For the prefix resolution: 

« Workfiles 1, 2, and 3 can be located at the same device since 
they don't interfere with each other. But they should be 
separated freir the index workfile (EFSURIDX) if one exists. 

• The SORT/MERGE workfiles, SORTWKnn, should be kept on a 
separate device from workfiles 1, 2, and 3. The normal 
SCRV«EFGE guidelines for the placement of SORTWKnn apply. 
Typically three SORT/MERGE workfiles on separate direct access 
devices give good performance. 

3- Fcr the prefix update execution, workfile 3 should he on a different 
volume from the data base data set (s) . 

4. The location of the control d^ta set DFSURCDS is not important for 
performance; it is used only at the beginning of the utilities. 

Size_of _W orkf i le _J 

The records, and their size, which will be written to workfile 1 by EL/I 
during initial load or reload are: 

Type 00« cne record will be written for each logical parent occurrence. 
If the logical parent has multiple logical child segment types, 
the record is written once for each logical segment type. 
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The size will be 48 bytes ♦ the length of the logical parent 
concatenated key if the data base is being initially loaded. 

TyFe 10. One record will be written fcr each logical child occurrence, 

The size will be 43 bytes plus the length of the lcgical parent 
concatenated key Jcnly initial load) plus the length of the 
virtual child sequence field if one is defined. 

Type 20. Cne record will be wri±ten for each logical child occurrence 
which has a LTF pointer and nc virtual child sequence field 
defined. The size is 43 bytes plus the length of the lcgical 
parent concatenated key if in initial load. 

Tyt-e 30. One record will be written for each logical child occurrence 
which has a ITE pointer and no virtual child sequence field 
defined. The size is 43 bytes plus the length of the logical 
parent concatenated key if initial load. 

Type 40. Cne record will be written for each index source segment 

occurrence. The size is 42 bytes, plus the length of the index 
search field (s) , including the four bytes for the /SXname field 
if any. This is the cnly record which will te written to the 
index work file. 

Note: The actual size of work file 1 can be found in the tape trailer 
label or the VIOC if it is on a direct access ievice. 

RS0iGl»iJIfiG^13& - .ga5ES_iITH - i06ICAi REI|3ICgJgI|S^SJCC^D4BX_IKEJ3[ES 

The following steps shculd be executed when reorganizing data bases with 
logical relationships and/or secondary indexes: 

1- Start with the prerecrganization utility, EFS0RPR0. Specify all the 
related EEC names in a DBE control statement (s) . However, no 
primary or secondary index EED names should be specified. 

2.. Unload all related HEAK/HIEAM data base (s) , using the HD 

Reorganization Dnlcad utility, DFSCRGUO. This should be done at the 
same time, that is, no data base processing between the unload and 
the prefix update of all connected data bases. The primary (HIEAK) 
and secondary index data bases need not and should not be unloaded 
separately. 

3. Change any physical attributes as needed. Refer to the section 
"Reorganizing a HEA* or HIEAM Data Ease" earlier in this chapter for 
the allowed changes. 

4. Reload the HDAM/HIDAM data base(s), using the HD reorganization 
reload utility, DFS0FGL0. Each reload of a data base will create a 
DFSURWF1 workfile, 

5. The other steps are exactly the same as for the initial load process 

(see Figure 5-8), that is, prefix resolution, prefix update, index 
unload and index relcad. 

Note: When unloading the existing secondary index data base, it 
must be a newly defined "empty" KSDS. So you should first delete 
the KSDS and redefine its space before the execution of the index 
unload utility (DFSURULO). 
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The HD reorganization utilities can be used to iaplement many different 
design changes to your data cases. The most common changes are 
discussed in the following sections. 

CHANGING A FHKSIC4I EEE 

The following rules and restrictions should be observed when applying 
structural changes to a physical data base: 

A- The HD unload utility must have been executed against the EED 

describing the current structure, and nc data base updates should 
have occurred since the unload. 

B. An existing segment type can fce deleted from the DBS provided all 
occurrences of this segment were deleted prior to execution of the 
HE unload utility. 

C. New segment types can be added to the new DBD provided they do not 
change either the hierarchic relationship among existing segment 
types or the concatenated keys cf logically related segments. {You 
cannot add a parent to existing segments.) 

D. Names of existing segments must not be changed during 
reorganization, that is, between unload and reload. Segment names 
can be changed before or after the reorganization. 

E. Any field statement except the sequence field (key field) can be 
changed, added, or deleted. However, DI/I will not change any 
segment data except as in (F) below. 

F. Existing segment lengths can be altered. If the segment is made 
smaller, EL/I simply truncates the segment. If the segment is 
extended, it will be filled with whatever exists in main storage 
beyond the end of the segment. The user should replace this via ar 
update progran. 

G. The access method may fce changed. SHISAM/HIDAM may be changed to 
HDAMo HDAH can be changed to either indexed method only if the 
randomizing module maintains root key seguence. 

AEEING LOGICAL BELAIIONSHIPS/SECCNDARY INDEXES 

The fcllcwing rules and guidelines should be observed when adding a 
logical relationship and/or a secondary index to an existing data rase: 

A. Eefore unloading the data base which certains the logical child, all 
the logical children must already exist in that data base. This 
segment, which at unload time is still a regular dependent segnent, 
must start with the ccrcatenated key cf the "would be" logical 
parent. Bemember, the HE reorganization utilities process only the 
segment prefix, never the segment data. 

If a logically related data base is to be added, its initial load 
process will generate a EFSUEWF1 file. No additional unload/reload 
of that data base is required. 

B. The HD unload utility must have been executed against the DEE 
describing the current structure, and no data base updates should 
have occurred since the unlcad. 
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C* lliil the HE unload, the DBD (s) are changed. And the 

pre re organization utility (DFSORPFO) Bust be run with the nev DEC(s) 
before the reload/initial load. This could also be done initially 
if the new LBV (s) have different names. Notice, the HD unload 
utility dees not need the control data set created by the 
prereorganizaticn utility. 

0. Prefix resolution (DFS0BG1C), prefix update (DFSOfiGPO), and index 
creation (optional: EFSUBUIO/DFSUBBIO) should then be perfomed as 
in figure 5-8. 

Exajp.ies 

1. Job //SAMP289 in IMS IS. PRIME JOB shows how to add a logical 
relationship to the Farts data base together with the initial lead 
of the related Custcier Orders data base. 

2. Job //SAHP389 in IBS* S.PRIMEJOB shows how to convert the phase 2 
Parts and Customer Crders data bases to their phase 3 versions by 
adding a secondary index to the Parts data base. Notice that no 
application program is required to add a secondary index. 

FEOBGANj;ZING_INJlN_gN!jIN!^ 

In our subset, we will set consider the reorganization of a data base 
while it is allocated to the online IMS/VS control region. Therefore, 
the reorganization procedures in the IMS/VS-DB/DC environment are 
exactly the same as for the IMS/VS-DB only environment. 
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CHAPTER 6. TATA EASE RECOVE&I 



&1!M 15 EECOVEEY? 

Lata tase recovery is, in its simplest form, the restoration of a data 
base after its (partial) destruction due to some failure. The preceding 
sentence defines the three basic elements in recovery: 

• The data base 

• The failure 

• The restoration 

Their relationship is: "The restoration eliminates the effect of the 
failure on the data base." 

The basic principle of almost any data base recovery mechanism is 
maintaining duplicate data. Periodically, a copy of the data in the 
data base is saved. This ccpy is normally referred to as a back^ug or 
AMSS £PJs.Y- These image copies normally reside on magnetic tapes. In 
addition to this, the changes made to the data in the data base are 
saved, at least until the next image copy. See Figure 6-1 for an 
overview. 
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Figure 6-1. Concepts of Data Ease Recovery 
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The recovery process then includes the following four steps: 

1. Determine the cause of the failure. 

2. Correct the cause of the failure. 

3. Reconstruct the data base using the image copy and the saved 
changes. 

4. Resume processing at the point of failure. 

Each of the above steps can cause, in practice, a variety of activities, 
the intention cf this chapter is to provide you with guidelines for, and 
examples of, procedures tc handle these activities. 

1HC_AP.PR01CH1[S 

With EL/I, twc approaches are, in general, available to protect the 
integrity of your data bases: basic recovery and DL/I recovery. 

BASIC RECOVER? 

After each back-up copy is made, all input data to the data base update 
programs are saved until the next back-up copy is made. In case of 
failure, the data base is restored, using the back-up copy. Next, all 
update programs executed during that pericd are re-executed, with 
exactly the same input data and in exactly the same sequence. The 
regenerated output replaces the original output. DL/I provides 
utilities to create the back-up copy and to restore the data base. This 
approach is referred to in the following discussion as basic recovery. 
See Figure 6-2. 
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Figure 6-2. Basic Data Ease Becovery 



DL/I BICOVIBY 

The second approach uses the DL/I log facility. During processing of 
the data bases by application programs, all changes made to the data 
base are automatically logged cc the DL/I leg data set. A DL/I utility 
is provided which allows you to accumulate all changes made to the data 
base by all processing programs in a single change accumulation data 
set. Only the last copy of a data base change is kept in this data set, 
thus reducing the volume of tape required. When a failure occurs, you 
restore the latest back-up copy of the data base, using a DL/I utility, 
which at the same time merges the change accumulation data set into the 
restored data base- This brings the data base up to the point of the 
failure. In addition, a separate utility is available to back out 
(undo) the data base changes of a failing program. This approach is 
referred to in the following discussion as DL^I recovery- See 
Figure 6-3. 
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Figure 6-3. EL/I Becovery 



HHICH ONE 10 CHOOSE 

EL/I recovery has several advantages over the basic recovery: 

No need to retain the input data sets 

No rerun cf update processing programs 

Only the affected data sets need to be recovered 

No time synchronization problems if the programs are date dependent 
or have been modified in the interim 

Simpler administration: only the back-up copies and log data sets 
are required 

No duplicate output 

lor the IMS/VS data communication facility, a log data set for the 
cnline data bases is mandatory- There is normally no retained input 
from terminal transactions. It is recommended that you establish 
DL/I recovery procedures before going online. 
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Based on the above advantages, the recommendation is to implement DL/I 
recovery unless you have: 

• Only one or two data bases, and, 

• Lov data base update rate, and, 

• Very freguent (daily) back-ups, and, 

• Mo plans for online processing. 

Befcre describing the two recovery approaches, we will first discuss the 
DL/I logging facility and associated recovery utilities. 

32I-E£^I-1CGGING_FACI1I2J( 

The Dl/I logging facility is the cornerstone of the recovery utilities 
of DL/I. This facility, operating as an integral part of DL/I, 
automatically writes all before and after images of updated data base 
segments to a central log data set. Each log data set, created with a 
DL/I batch program execution, is one sequential data set. It must 
reside on magnetic tape in cur subset. You must specify 
DISP=(, KEEP, KEEP) or DISP= ( ,CATLG ,CATLG) for the log data set, that is, 
DISP^MCD is not allowed. 

In our subset, we will assume the use of the log tape write ahead 
function (specify: OPTIONS LTHA=YES in the DFSVSAMF control data set). 
For mere details, see "Defining the IMS/VS Data Base Buffer Sutpools" in 
Chapter 7, "Installing IMS/VS. « 

The log tape write ahead |LTHA) function will assure that no data base 
change will be written to physical data base storage before the 
corresponding log records are physically written to the log data set. 
With this prevision and the log close function of the log recovery 
utility, there is no risk cf lest data base changes, even in the case of 
an abrupt system breakdown. 

A log data set is created by adding a //IEFBDEF DE... statement to the 
JC1 of the batch execution jcb. 

N2l§s: 

1. A log data set is not created when a data base is initially loaded 
(that is, when the processing option "L" or "LS" is selected in the 
PCB) . 

2. IMS/VS uses the OS/VS ESTAE facility to flush the log buffers and 
clcse the leg data set in the event of an abnormal termination. In 
addition, for batch jobs only, the data base log buffers will te 

written to CBSE. 

THJ_DL^J_BECOVEPY_0TILITIES 

DL/I provides four utilities for recovering a data base. The diagram in 
Figure 6-U illustrates the relationship between these utilities. 
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Figure 6-4. lata Base Recovery Utilities 

A description of these utilities and their basic functions follows: 

1. Data Ease Image Copy utility for creation of image copies of data 
bases . 

2. Lata Ease Change Accumulation utility for accumulation of data base 
changes frcm DL/I log tapes since the last complete image copy, 

3- Data Base Becovery utility for restoration of the data case, using a 
prior data base image copy and the accumulated changes from DL/I leg 
tapes, 

k. Data Ease Backout utility for removal of changes made to data bases 
by a specific application program. 

A fifth utility program, the EL/I System Log Recovery Utility 
(DFSULTRO), is used to close the DL/I Log in the event of an operating 
system or hardware failure, thus enabling use of the log by the four 
principal programs cf the recovery system. 

For those data bases which consist of multiple data sets, recovery is 
done by individual data set. To recover a complete data base composed 
of multiple data sets, data base recovery must be performed for each of 
its component data sets. 
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DATA BASE IMAGE CCPY CTILIT* (EFSUEMEO) 

The Data Ease Image Copy utility creates a copy of the data sets within 
the data bases- is illustrated previously (see Figure 6-4), this output 
is used as input to the Data Base Recovery utility- 
Multiple data sets can be ccpied with one execution of the Image Copy 
utility.. All data sets of a data base should be copied at the same time. 
In our sufcset, we presume that all data base data sets are dumped at the 
same time, that is, no intervening data base processing. 

A flov diagram of the Data Ease Image Copy utility is shown in 
Figure 6-5. 
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Figure 6-5. Data Base Image Copy Utility 



JCL_Statements 

The Data Base Image Copy utility is executed as a standard CS/VS job. 
The fcllcwing JCL statements are required: 



EXEC 



IMS 
DD 



SYSPFIKI 
ED 



This statement must te in the following form: 

PGK=EFSBI<C00,FAEH= , ULU,DFSODME0• 

Defines the library containing the DBD that describes 
the data base to be dumped. This is usually 
DSNAME=IKSVS.DBDLIB . 

Defines the output message data set. 
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datain Eefines the input data set to be dumped- The ddname 
ED on this statement must be the same as the name in the 

EED that describes this data set; the ddname must alsc 
appear on the utility control statement. One ED statement 
of this type must be present for each data set to fce 
dumped. The data set must reside on a direct access 
volume. 

dataout Eefir.es the image copy output data set. One DD 

ED statement is required for each data set to be dumped. 

The ddname may be any 1- to 8-character string, but the 
ddname must appear in the associated utility control 
statement. The output device must be either direct access 
or tape. Standard labels must be used. LEECL and BLKSIZE 
are calculated by the utility and should not be provided 
in the JCL, 

SYSIN Eefines the input control statement data set. 
EE 

2tilitx_Control_ Statement 

One control statement is required for each data set to be dumped. 

1 U 13 77 80 

r «.•------------------------.-!--------- — ----- ^ 

I I 

| E1 ES1PAETS EE1PAETS EFSUEOMF ! 



Position Eescription 

1 This must be the characters 'El*. 

4 This irust fce the name of the physical EED that includes 
the dcname of the data set to be dumped. 

13 This must be the ddname of the input data set to be 
dumped. It must appear in the referenced EED, and a 
ccrrespcnding DD statement must have been provided. 

22 This must be the ddname of the output data set. A 
corresponding EE statement must have been provided. 

Note: All ether fields must be blank in cur subset. 

The Data Ease Image Copy utility provides the following return codes: 

Code Meaning 

Successful ccirpleticn of all operations. 

4 Warning message issued. 

8 One or more operations not successful. 

16 Severe errors have caused the job to terminate 
without completing all operations. 
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These return codes can be tested by the COND= parameter on the EXEC 
statement of a subsequent job step. 

Exajrj:les 

Job //SAMP180 in IBSVS. FEIKEJCE shows the JCL for the image copy jot of 
the phase 1 Parts data base. Jcb //SAMP380 shows the image copy of all 
our sample phase 3 data bases. 

DATA BASE CHANGE ACCU*CIATIC* UTILITY (DFSUCUMO) 

The function of the data base change accumulation utility is to create a 
seguential data s€t that contains only that information from the log 
tapes which is necessary for recovery. This accumulation log data set 
is to be used by the data base recovery utility. This accumulation is 
done by sorting only the required log records (latest version) in 
physical record within data set sequence. This provides efficient data 
base recovery whenever needed. The number of log tapes will be 
significantly reduced. This utility invokes the Sort/Merge Program in 
your CS/VS installation- 

The change accumulaticc utility can be run independently of DL/I 
application programs. The new output data set created by Change 
Accumulation is used bj the data base recovery utility. Figure 6-6 
depicts the sources of input tc the data base change accumulation 
utility and the output created by this utility. 
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Figure 6-6. Data Ease Change Accumulation Utility 



The input to the data base change accumulation utility consists of: 

1. fill log tapes created since either the last image copy utility 
execution or the last execution of this utility. 
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2- The previous change accumulation data set. This would be the output 
from the last execution of this utility. The first change 
accumulation run after a new image dump must not include any old 
change accumulation data set, that is, those created during the 
previous period. 

3, The DBD library which is normally called IMSVS.DBDLIB. 

U« An optional control statement (ID). 

Output from the data base change accumulation utility consists of a new 
change accumulation data set* This is a sequential data set containing 
the combined data fcase records for all data base data sets. 



reinstatements 

The data base change accumulation utility is executed as a standard 
OS/VS job. The following JC1 statements are required: 



EXEC 



This statement must be in the following form: 
PGM=DESUCCMC 



SYSPRIM 

ED 

IBS 
ED 



Defines the output message data set. 



Defines the library containing the DBDs that describe 
all data bases tc be accumulated. This is usually 
BSNAME=IMSVS.DBDLIB. 



SYSOUT 
ED 



SCETLIB 
DD 



Defines the output message data set for the Scrt/Merge 
program. The Sort/Merge program specifies AP (all 
messages tc printer) • 

Defines a data set containing load modules for the 
execution cf Sort/Merge. This is usually 
ESNAME=SYS1.S0RTLIB. 



SOETHKnn 
DD 



EfSUCUMN 
DD 



EESUCUMO 
DD 



These DD statements define the intermediate storage 
data sets for the Sort/Merge program. The data sets 
normally reside en a direct access volume; however, tape 
can be used. (For specification of number and size of 
intermediate storage data sets, refer to the applicable 
Sort/terge manual. 

Eefines the new accumulated change output data set. 
The data set can reside en a tape or a direct access 
volume. The output is blocked to maximum device capacity, 
up tc a maximum of 8K. Standard labels must be used. 

Eefines the old accumulated change input data set that 
is to be merged with the new accumulated change data set. 
If no old changes are to be merged, the following ED 
statement must be used: 

//EFS0COM0 ED DUMMY, DCE=ELKSIZE=100 

This is reguired in the first change accumulation 
execution after each new image dump of the data bases. 

This data set can reside en tape or a direct access 
volume. 
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DFSULCG Defines the leg input data set containing the change 
DD records to be accumulated. This data set can reside on 

tape or a direct access volume. 

SYSIN Defines the control statement data set. 
DD 

Utility,_Ccntrol_ Statement 

An optional control statement can be used to describe additional tatle 
requirements for this charge accumulation execution. If it is not 
included, default values are assigned as described below. 

1 31-33 80 

r * "•"""" " " ' " ---•% 

! I 

| IE Max Seg Length | 



1 Positions 1 and 2 must contain the characters "ID", 

31 Positions 31-33 contain the maximum length root sequence 
field contained within the log records to be processed. 
This value is used to pad the sequence field with binary 
zeros for sorting purposes- If there are no VSAM KSDS 
records to be processed, this value should be specified as 
U r the length cf the Relative Block Number field. This 
value must be in the range 1-236 and must be 
left- justified or supplied with leading zeros. The 
default value for this entry is 10. In our subset ycu 
must specify the maximum root sequence field of any HIDAM 
and/or SHISAM data base- 
Note: All other columns must he blank in our subset. 

I§turn_Ccdes 

The data base change accumulation utility provides the following return 
codes: 

Cede Meaning 

Successful coirpleticn. 

16 Unsuccessful Completion. 

These return cedes can be tested by the C0NC= parameter on the EXEC 
statement of a subsequent jet step. 

Examjale 

Jobs //SAMP181 and //SAMP361 in IMSVS.PRIMEJOB show the JCI to 
accumulate a log data set, with a previous accumulated log data set, 
into a new accumulated leg data set. 
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Note: The change accumulation utility can accept multiple leg data sets- 

as input. These log data sets must be specified as concatenated data 

sets in the DFSGLCG DC statement- The sequence of these data sets 

should be in the correct date and time sequence, that is, the oldest 
first. 

DATA BASE FECCVEEY OTIIIT* (DFSUEDBO) 

The data base recovery utility program will restore a physically damaged 
data set which is part cf a DL/I data base. This utility does not 
provide a means of recovery from application logic errors; it is the 
user's responsibility to ensure the integrity of the data in the data 
base. 

The data base recovery utility achieves a high rate of throughput by 
manipulating data sets individually in a physical sequential manner. 
The basic input consists of an image copy data set and, optionally, an 
accumulated change data set. 

The data base recovery utility program is executed in a DI/I batch 
region. Its fie* diagram is shown in Figure 6-7. 
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Figure 6-7. Eata Ease Recovery Utility 



JCl Statements 



The data base recovery utility is executed as a standard OS/VS job. 
Cnly one data set recovery is allowed for each execution. The following 
JCL statements are required: A JCB statement (defined by the using 
installation), an EXEC statement, and DD statements that define inputs 
and outputs are required. 
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IXEC This statenent must be in. the following form: 

FG^EFSBFCOOrPARM^UER^DFSUEDBCdbdname' 

where dbdname is the name of the DEE that includes 
th€ data set tc t€ recovered. 

IMS Defines the library containing the DBD that describes 

DD the data base data set to te recovered- This is usually 

ESNAMI=IMSVS.DBDLIB. 

SYSPEINT Defines the output message data set. 

ED If tlocked it itust be a multiple of 121. 

EFSUEUMF Eefines the iiiage ccpy input data set. It must be a 
DD data set created by the Data Ease Image Copy utility. The 

data set can reside on tape 01 on a direct access volume- 
Standard labels must be used. 

DFSUCUM Defines the accumulated change input data set. If no 
ED accunulated change input is supplied , this statement must 

be coded DE EUMMY. This data set can reside on tape or a 
direct access volume. Standard labels must be used. 

DFSULOG This statement should be coded as DD DUMMY in our 
DD subset- 

datasetl Defines the data set to be recovered. The ddname must 
DD be the same as the ddname in the DBD that describes this 

data set. It must also appear on the utility control 
statement. This data set must reside on a direct access 
volume. 

SYSIN Eefines the input control data set. 
ED 

Utility. Control Statement 

1 Q 13 80 
r" -^ 

I I 

| S BElPARTS DE1PARTS | 



L- 



Fcsiticn DescrjLEticn 

1 This must te the character • S 1 . The 'S* defines this 
statement as a data base recovery utility control 
statement. 

U This must be the name of the DBD that describes the data 
base containing the data set to be recovered. This name 
must alsc appear in the PARM field of the EXEC statement. 

13 This must be the ddname of the data set to be recovered. 
It must be the same as the ddname in the DBD and dataset! 
EE statenent. 

fifiiS : AH other positions must be blank in our subset. 
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Jfia^JB Codes 

The data tas€ recovery utility provides the following return codes: 

Ccdg Meaning 

Requested recovery successful. 

4 Warning message issued 

8 Serious error occurred, recovery terminated 

16 Catastrophic errcr occurred; recovery unsuccessful 

These return codes can te tested by the COND= parameter on the EXEC 
statement of a subsequent job step. 

Examples, 

Job //SAME182 in IMSVS. EBIHEJGE gives the JCL to recover the phase 1 
Parts data base. Jcb //SAMP383 gives the JCL to recover all the phase 3 
data bases using a change accumulation log data set. 

DATA BASE EACKOUT 01ILI1Y (DFSPBO00) 

The data base backout utility removes changes in the data base which 
were made by a specific failing program. The following limitations 
apply: 

• The log data set of the failing program must be on magnetic tape; 
the tape is read backwards.. 

• No other update programs should have been executed against the same 
data base (s) between the time of the failure and the backout. 

The program operates as a normal DL/I batch job. It uses the PSE used 
by the program whose effects are to be backed out. All data bases 
updated by the program must be available to the backout utility. 

A leg tape is created during the backout process. This log tape, 
preceded by the log tape produced for the failing job, must te included 
in the next change accumulation run, as any other log tape. This tape 
oust not be used as input to any subsequent backout attempt. 

Note: For a multiple volume data set, the VOL parameter of the JCL 
statement specifies the volumes in ascending sequence. 

figure 6-6 presents a summary of conditions that terminate the 
processing of the data base backout utility. 
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r 

I Summary of Conditions Terminating the Processing of the 
\ Data Ease Backout Utility 



| CHKE-ID specified. | CHKE-ID not specified. 

I 

| 1. CHKP record requested. |1. First CHKF record encountered,* 

I 

| 2- The Accounting record fcr opening the log data set. 



|*Note: The order of occurrence is referenced as from the end of 

|the Log tape toward the start of the Log tape. (Bead -back ward 

(processing.) 

c . . .................J 

Figure 6-8. Conditions That Terminate the Data Base Backout Utility 

Notes.2 

• If checkpoint/restart is net used, then backout always backs out all 
the data base changes of the program. 

• If checkpoint/restart is used (program uses XRST and CHKP calls) , 
then backout will enly dc backout if the specified CHKP-ID is found 
on the leg tape during read forward. If no CHKP-ID is specified 
then the last one on the leg tape is used (the first one encountered 
during read backward). 

• If, when using checkpoint/restart, you want to be able to completely 
back out a jet (steps) , you must issue a CHKP call immediately after 
the XBST call, that is, before any real data base activity. The 
CHKP-ID of this call can then be used for a full backout operation. 

Figure 6-9 depicts the data set requirements for the data base backout 
utility. 
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Figure 6-9. Cata Set Requirements for the Data Base Backout Utility 



££i Statements 

The data base tackout utility is executed as a standard DL/I batch job. 
The following JC1 statements are required: 



EXEC 



IMS 
EE 

IMSLCGB 
DD 

IEFBDER 
DD 



dataset 
EE 



This stateient must be in the following form: 

PGM = DFSRBC00 r PARM=»DLI r DFSBBO00 # £:sbname l 

where psbname is the name cf the FSB used by the program 
to be backed out. 

You can also use the DLIEATCH procedure to execute this 
utility. See Chapter 7, "Installing IMS/VS," for 
additional information on using the DLIBATCH procedure. 

Concatenates the IMSVS.PSELIE and IMSVS.DEDLIB 
libraries. 

Eescribes the input log file. It must be a tape file; 
read -backwards is used. 

Eescribes the system log tape created during backout. 
The data set usually resides on tape. However, a direct 
access volume can be used. 

These are the data base ED statements required by the 
PSB referenced in the EXEC statement. This data set must 
reside on a direct access volume. One DD statement is 
required for each data set of the referenced data bases. 
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SYSIN Required only if a CHKPT control statement is supplied. 

EE 

EFSVSAMP Eescribes the data set that contains the buffer 
DD information required by the DL/I buffer handler. This DD 

statement is required if the data bases described by the 
dataset EE statements are VSAM data sets. For additicnal 
information, see the discussion en "Defining the IflS/VS 
Data Base Euffer Subpools" in Chapter 7, "Installing 
IMS/VS." 

V.%il3tl2 £221121 Statejs€£t 

Cne optional control statement can be used if the program uses the EI/I 
batch checkpoint/restart facility. 

1 7 80 

r ------ ---_--.-.--«•------.----.-._--.•-------- — «.--•«-..-. .........^ 

I I 

| CHKPT PPUBC010 | 

I I 

Position EesciiEtiou 

1 Positions 1-5 must be the characters •CHKPT 1 . These 
characters define the control statement. 

7 Shis is the 8-character checkpoint IE supplied to DL/I 
with the •CHRP 1 call. The ID is displayed as part of 
message EFS681I at the time the 'CHRP* call is" made. 

If no IE is specified, the last checkpoint on the log tape 
vill be used. 

Mote: All other positions should contain blanks. 

i!l£J2IJ3 Cod§s 

The Data Ease Eackout utility provides the following return codes: 

Code Sii.Ei.BS 

Eackcut successful. (DFS395I) 

a PSE incorrect. (DFS3S6I) 

8 Unable to open data base. (DFS397I) 

12 and Severe error condition; processing terminated, 
above 

These return codes can be tested by the COMD s parameter on the EXEC 
statement of a subsequent job step. Each return code, however, causes a 
message to be printed. 

Jobs //SAMP177 and //SAMP36t< in IKSVS.PRIMEJOB show the JCI for the 
backcut of the FE1CEP0R program executions for phase 1 and phase 3, 
respectively. 
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SYSTEM LOG RECOVERY UTILITY (DFSOLTRO) 

This utility can be used to clcse a log data set when DL/I or CS/VS 
fails tc do so. This will typically be required after an OS/VS, tape 
unit, CPU, or power failure. Note that when DL/I abends, the log data 
set will usually be closed ty CS/VS- The OS/VS message IEF285I (data 
set KEPT) indicates that this has been done- Two steps are required to 
clcse a leg data set with DFSULTRO. See Figure 6-10- Each step requires 
a separate execution cf CFSUITRO. 
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Figure 6-10. Closing the System Log with DFSULTRO 



SteE J J I2£ Mod® 

In the DUP mode, DFSULTRC reads the log data set and copies it to a new 
interim log data set- ft listing is produced of the error blocks. In 
the situation cf the unclosed leg tape, only the first error block is 
generally of interest. The sequence number of this error block (A00001) 
should be specified in the control statement of the second execution of 
DFSULTRO. 

Notes: 

1- If the log tape contains read errors before the end of the leg data 
set, these would alsc be listed. In our subset we will not cover 
the correction of these errors- In that case, we will disregard 
that log tape data set ard recover the data bases to the point of 
the start of the failing program- Following that, a full rerun of 
that program would fce required. 
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2. Because the DFSCLIRO cnly checks the leg record sequence number, old 
data from a previous (log) data set will be regarded as valid leg 
data. This old data will therefore be copied to the interim log 
tape after signaling its initial sequence number break as an error 
block. Without checking the actual contents (that is, timestamps) 
in the leg records ycu might not be able to distinguish this 
situation from read errors befcre the end of the current data set as 
discussed in note 1 above- To avoid this ambiguity you can use 
"clean" (that is, no data at all) leg tapes cr prewrite the log 
tapes vith tape marks. 

3. If the DUP mode of DF30ITFO did not find an error block at the end 
of the current log data set, it will terminate normally, or abend. 
In that case- the log tape produced by the DUP mode is a valid log 
tape, and the SEP mode is not necessary. 

4. For mere details on the IMS/VS log records, you should refer to the 
sections entitled "System log Records" in Chapter 2, "System 
Maintenance/Tuning Facilities" cf the IMS^VS System Programming 
Reference Manual. 

Step 2: ||P Mode 

The PEP mode of EFSULTFO copies the correct blocks from the interim log 
data set, produced by the DUP mede execution, to a new log data set. At 
the end it will close that log data set, omitting the block in error as 
specified by the control statement. 

JCL Statements 

JOE (ACCTGINFORMAIION) 

EXEC PGK=EFSUIT50 

SYSODT=A,DCB=(RECFM=FBA,IRECL=133) 
UKIT=3400,VCI=SER=LOG01,ESN=IMSLOG, DISP=OLD 
UNIT=3400,VOL=SER=NEWLCG,DSN=IMSLOG, 
DI£P= (NEW, KEEP) ,DCB=D£CRG = PS 
DUKMY,DCE=EIKSIZE=1460 

2iiiiil Control Statements. 

CUP node 

The following control statement is reguired in our subset: 

Beginning in 

Colujin Forjnat MSlSiUS 

1 COP Indicates DOP mode. 

5 ERRC-nnnnn Indicates the maximum number of input 

I/C errors or sequence errors accepted 
before job termination, nnnnn must be a 
5-digit numeric with leading zeros. 
Recommended value: ERRC-00010. 



//RECOVER 


JO 


//STEP 


EX 


//SYSPEINT 


EE 


//IEFRDER 


BE 


//NIWEEFR 


EI 


//NEKRDER2 


DC 


//SYSIN 


EE 
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REP Mode 

The following control statement is required in our subset: 



Beginning in 

Column, iPJUat 



1 



HIP 



SEQ=AXXXXX 



16 



CLCSE 



Indicates SEP mode. 

Indicates the identification number of 
the block in error. The identification 
consists of the letter "A M followed by a 
5 digit integer, the error block sequence 
number (A00001 for the first error block). 
The number is provided in the listing 
output of the DOP step. 

Close the output tape right befcre this 
error block . 



Catalcg_Considerations 

In general, log recovery is only required in case of 
failure; that is, when the leg tape is net closed, 
implies that the jobstep termination processing did 
consequence the new leg data set was not cataloged, 
catalog the recovered log tape in the second phase o 
process. However, this should be verified by compar 
with the manual leg tape registration by the operato 
circumstance should the input tape for log recovery 
with the |"duplicate") output tape for backout and d 
processing. Special care must be used if multi-volu 
written and only the last vclume is used for log tap 



hardware or OS/VS 
This normally 
not occur. As a 

Therefore we 
f the log recovery 
ing a list catalog 
r. Under no 
be used together 
ata base recovery 
me log data sets are 
e recovery. 



Examgles 

Jobs //SAMF190 and //SAKI19 1 in IMSVS. PRIMEJOB show the DUP and REP 
modes, respectively, cf DFSULTRC. 

JiSIC RECOVERY PROCEDORES 

The following guidelines shculd be observed when designing basic 
recovery procedures: 

• The image copies of all data base data sets should be made at the 
same time. Mo intervening (update) programs should be executed 
against the data bases. 

• A rigcrcus registration scheme should be established fcr the image 
copies and all prcgran input and, optionally, output. 

• All program input should be saved until the next image copies are 
made. 

• In case correction cf the error requires program changes, the old 
versions should be kept until the next image copies are made. 
Otherwise reruns, if necessary, could produce different results. 
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• The data bases oust be restored immediately after any failing update 
job. The failure could be an application program, Dl/I, CS/VS, or 
hardware error- Next, all data bases should be restored. Then, the 
application progra&s executed since that image copy vas made should 
be reexecuted in the original sequence- 
Note: As stated in the first part of this chapter under "Khich One To 
Choose," you should realize th€ limitations cf the above basic recovery 
procedures. In roost cases the DL/I recovery procedures as outlined in 
the following section are far more desirable. 

EXAKPLES 

Job //SAMP180 in IMSVS.PR IMIJOB can be used to make an image copy of the 
phase 1 Farts data base. Job //SAMP182 can be used to restore this data 
base. These jobs shew how the image copy and restore utilities are used 
in a basic recovery envirccaent. 

£iZI IJCOVEBY PBQCJCORES 

The following procedures can be used as a basis for the recovery 
procedures at your own installation. It is strongly recommended that 
you exercise and enforce such procedures before going into a production 
phase with ycur data bases. 

ASSUMPTIONS AND BES1BICTICKS 

1. Image copies of all data sets of all data bases are made at the same 
time, that is, no intervening data base processing. 

Note: The above restriction is based solely en the subset approach; 
it is net a DL/I requirement. 

2. Nc ether update program may have been executed after the failure 
involving the data base in error. If that should occur, you must 
restore all affected data bases and rerun the programs in proper 
sequence. 

3. After each new image copy of your data bases, you must run the first 
change accumulation with a dummy old change accumulation data set; 
that is, never use a leg tape cr change accumulation data set of the 
previous period. 

POSSIBLE FAIL ORES 

The table in Figure 6-11 lists the most ecromen failures, together with 
their symptoms, which can occur in the batch processing of Dl/I data 
bases- For each failure, an error class is given- This error class 
determines the reguired recovery actions. See Figure 6-12- 
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EBBCB 




FAILURE/SIIUA1IGN DESCBIPTICN | 


SYMPTOMS | 


CLASS 


1 1. 


OPEBATING EBBCB 








1. 1 Job cancellation ! 


X22 ABEND 


A 




1.2 Wrong input cr wrong data base 


INCONSISTENT RESULTS 


A 


|2. 


APPLICATION PROGRAM ERROB 








2-1 Wrong logic/output 


INCONSISTENT BESULTSi 


A 




2.2 Abend 


OSEB ABEND 


A 


I 3. 


EL/I ERBOB 








3. 1 Abend 


DL/I ABEND 


A 




3.2 Loop or wait state 


CANCELLED (X22) 


A 


I 1 *- 


CS/VS EBBCB 








4.1 Abend 


BE-IPL 


C 




4.2 Loop or non-dispatchable 


RE-IPL 


C 


|5. 


HABDWABE 








5.1 Bead I/O error on a data base 


I AO status code ♦ 






data set 


DL/I message DFS451A 


E 




5..2 Write I/C error on a data base 








data set 


IDL/I message DFS451A 


I B 




5.3 Power failure, machine check 


BE-IPL 


I c 



Figure 6-11. Possible Failures during Data Base Processing 

Note: Opon receipt of message DFS451A, the OS/VS system console 
operator should (a) take action to stop the execution of subsequent DL/I 
jcbs and (b) reply "ABEND". 

COBBECTING TBE CAOSE OF THE FAILDBE 

This activity is completely dependent on the type of failure. Cften, 
the action to be taken is beycnd the DL/I environment, for example, 
system/power failure. If the error is ir DL/I, the IMS/VS Messages and 
£2d.§s,-§§I§r^2S§-jJ§fi.ual must be consulted. If it is a severe error 
condition^ the'lBM field Engineering Program System Bepresentative 
should be notified. Appendix A in the IMS^VS^Messaaes^and^Ccdes 
li^SESS£Jl_liJiISiS3i provides guidelines for doing this. 

EECOVEBY 1ASKS 

The subsequent recovery tasks to be performed for each defined error 
class (Figure 6-11) are listed in Figure 6-12. 
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ERROR 
CLASS 


RECOVERY TASKS 


NOTES 


LOG CLOSE 
(DFSULTRO) 


CHANGE 

ACCUMULATION 

(DFSUCUMO) 


DB RECOVERY 
(DFSURDBO) 


BACKOUT 
(DFSBBO00) 


RESUME PROCESSING 

(APPLICATION 

PROGRAM) 




EXCLUDE 

CURRENT 

LOG 


INCLUDE 

CURRENT 

LOG 


ONLY 

AFFECTED 

DATA 

SETS 


ALL 

DATA 

SETS 

USED BY 

PROGRAM 


ALWAYS 

CURRENT 

LOG 

(must be 

a tape) 


RESTART 


RERUN 


A 












# 


* 




1. current log + 
output log of 
back -out must both 
be included in 
next change 
accumulation run 


B 






* 


* 




* 


* 




1. see A1 

2. if program 
was successfully 
completed, no 
restart required 


C 


* 










* 


* 




1. see A1 


D 




# 






* 






* 


1. the current, 
bad, log must not 
be used in any 
further back-out 
or change 
accumulation 


SAMPLE 
JOB 

# 


190 

+ 
191 


181,381 


182,382 


382+383 


177,384 


178 


initial 

program 

executions 





Figure 6-12. Data Ease Recovery Actions 

The data base backout utility is net required for a retrieve-only 
program. The additional error class "D" would occur if for any reason 
the current log data set is unusable. The current log data set is the 
one being created when the failure occurred. 

Possible causes for this cculd be: 

• Log data set close (DFSCLTRO) failed, 

• Lost log data set due tc operational error, 

• I/O errors on the log data set during change accumulation. 

The recovery tasks in Figure 6-12 must be executed in sequence from left 
to right- Hhenever an errcr cccurs during an A, E, or C error 
correction, ycu can fall tack upen the errci class D procedure. 

If an error cccurs during the recovery of a class D error, you have to 
fall back to previous image copies and log change accumulation data 
sets. 

IMAGE COPY/LOG ADMINISTRATION 

A rigcrous administration of data base image copies, log data sets, and 
log accumulation data sets is a necessity for data base integrity. He 
will now discuss an adninistraticr scheme fcr this. In this scheme, we 
will use the generation data group facility of OS/VS. It would form the 
basis of your own scheme, adapted to your installation standards and 
requirements. 
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At a minimum yea should set up a manual registration scheme for the leg 

data sets, change accumulations, and image dumps. 

Two sets of fcrms could be used. One form. Figure 6*13, is used to 

register all the DI/I jobs which produce log data sets. 



El/I LOG TAPE JORH 



DATE: 



PERIOD: 



TIME 



VOL OH I (S) 



JOE/STEP 



IF FAILURE 

IAST 

CHECKPOINTID 



REMARKS ANC 
ERROR DESCRIPTION 



Figure 6-13. Sample DL/I Leg Tape Form 

U2tj§s: 

1. All DL/I jobs should be listed, also the backout and recovery jobs. 

2. If multiple log volumes are created in one job (step) , they should 
be listed in time sequence. 

3- A new period starts after each image copy. 

<J. Optionally, the data set came of the log data set should be 

registered- Normally this would always be the same or a generation 
data group, in which case only the generaticn number would be 
registered. 

The second form is used tc register the image copy and change 
accumulation jobs during each period (Figure 6-14). 
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r 

|DL/I Change 


Accumulation Form DATE: 
INFUT 


PERIOD: | 
t ODTPOT | 




DED | DATA SET 


I DATA 


SET|VOLOME(S) | 


II 1 lit 
|IMAGE | | ill 

I CCFY | | 111 

II 1 lit 


| | C1D 


ACCOKUIATICN | ICG DATA SETS 


| NEW 


ACCUMULATION | 


| |DATA 


SETtVOLUME(S) |DA1A SETJ VOLUME (S) 


| CAIA 


SET| VOLUME (S) | 


|CFANGE| 
|ACCOM. | 


I t t 
t 1 1 
1 1 t 
1 1 1 
1 1 1 
t 1 t 
t 1 1 
1 1 1 




1 1 
1 t 
1 1 
1 t 
1 t 
1 t 
1 ! 
1 1 



Figure 6- 14- Registration of Image Copies and Change Accumuleticns 

Notes: 

1. Each period starts with an image copy of all data base data sets. 

2« When generation data grcups are used, only the generation number 
need te registered. 

3. The first change accumulation run after the image copy should not 

have any old log tape or change accumulation tape as input (that is, 
//DFSUCUMO EE DUMMY, DCB=BLKSIZE=100) . 

fxam£les 

In our phase 3 sample jcbs, we use generation data groups for the data 
set image copies, the log data sets, and the accumulation data sets. 

FREQUENCY CF IMAGE CCEIES AWE CHANGE ACCUMULATIONS 

The freguency of image copies is dependent on your installation 
environment. It is a trade-cff between the necessary recovery costs in 
case cf failure and the cost of taking the image copies. 

The basic recommendation for taking image copies is: 

• Immediately after initial lead of the data bases- 

• Immediately before data base reorganization, if the old space is 
deleted during reorganization. 

• Immediately after data base reorganization. 

• Once each week. 
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The basic recommendation fci the change accumulation is once a day. 
Another approach would be tc perform change accumulation as a second 
step, controlled via condition codes, in every EL/I update jcb. 

E§!§fiii22_l££i2£_2£_5l§9§_£2£2_32d_L23_,£3i§_Sets 

Tc protect yourself against unusable image copies, logs, and change 
accumulation tapes, you should retain those tapes for at least two or 
three periods (a period is defined as the interval between two 
subsequent image copies). A suggested retention scheme, assuming a one 
week period, would be: 

• Log tapes are retained two weeks or until the time the next image 
copy is made. 

• Change accumulation tapes are made at least daily. The last one of 
the period is retained two extra periods- 

• Image copies are retained three periods. 

VSAM_CATAICG_CCNSIC|BATICSS 

It is strongly recommended that you use a separate VSAM user catalog for 
your data base data sets. When your installation grows, you should 
consider a user catalog for each application or project. 

In case of an error in the user catalog, you should first try tc correct 
the problem with the OS/VS Access Method Services VERIFY function. If 
this fails, the following procedure can be followed (VSAM 2 only) : 

1. Perform Access Kethod Services: ALTER EEMOVEVOLUMES 

This will delete all the data spaces owned by the user catalog and 
the user catalog itself. Ycu should specify all the volumes owned 
by that user catalog. 

2. Perform Access Method Services: DEFINE 

A new user catalog and new data base data space. 

3. DL/I 

Recover all the affected data base data sets. 

Warning: The above procedure completely erases (that is, overwrites 
with binary zeros) all VSAM data space, including the user catalog on 
the specified volumes. You should use this only if the VSAM user 
catalog has become inaccessible. For more details see also Ferform 
Access Method Services: "VSAM Volume Cleanup." 

Additional factors should be considered when setting up recovery 
procedures for data bases used by an online IMS/VS system. 

As discussed in Chapter 3, "Data Communication Design," a dynamic log 
data set is used by the online system for recording data base changes, 
as well as the leg tape. Abending online programs are automatically 
backed out by the online system using the dynamic log records. In 
addition, if the system should fail while an application program is 
active, any updates made by that program will be automatically backed 
out when the system is restarted. In our subset, if the program was a 
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BMP the updates are automatically tacked out to its most recent 
checkpoint. Eecause of this automatic backout, the operator will 
usually need to run the recovery utilities only vhen there has teen a 
major system failure, generally one which entails a re-IPL of CS/VS, or 
when there are I/C errors on a data base. 

The recovery procedures outlined later in this chapter make use of the 
DL/I recovery procedures and utilities described earlier in this chapter 
as well as an additional log tape maintenance utility, the System Log 
Terminator utility. 

SYSTEM LOG TFEMINAIOS UTILITY (DFSFLOTO) 

At the time of a system failure, the System Log Terminator utility can 
be used tc recover any log data that may have been lost as a result of 
the failure. A storage dump teken at the time of failure is required. 
This storage dump can be the SYS1.DUMP data set, or a stand-alone dump 
output tape- The log terminator program: 

• Locates the log work area, buffers, and control blocks in the 
storage dump. 

• Positions the log tape and writes the remaining buffers. 

• Closes the log data set. 

Detailed instructions on running the utility, and the possible error 
messages that may occur are described in the IMS^VS Primer Master 
leili£§2 S£§IS l2li§ Guide. 

Figure 6-15 shows the data set requirements for running the System Log 
Terminator utilitj- 





DFSFLOTO 



SYSTEM LOG 
TERMINATOR 



OUTPUT 
MESSAGES 



Figure 6-15- Running the System Log Terminator Utility 



JCL_ Statements 

The System Log Terminator utility is executed as a standard OS/VS jcb. 
The following JCL statements are required: 

EXEC This statement must be in the following form: 
PGM=DFSFLCTO 

SYSPEINT Defines the output message data set. 
DD 
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LCGTAPE Defines tfce log tape tc be terminated. This data set 
DD must have had a disposition of (NEW, KEEP) at execution 

time. 

EUMP refines the SYS 1. DUMP data set, or the stand-alone dump 

DD data set. The DCB information for this data set should be 

obtained from the CS/VS system programmer in ycur 

installation. 

ExajjDles 

//TERMIN JOE (ACCTINGINFO) 

//STEP EXEC PGB=DFSFICTO 

//SYSPRINT DC SYSO0T=A 

//LCGTAPE DD DSN=IMSLCG,VCL=SER=LOG00 1,UNIT=3U00-4, DISP= (,KEEP) 

//DUMP CD DSN=S1S1. DUMP, VOL=SER=SYSDKP,UNIT= 3400-4, DISI=CLE, 

// IABEI=(,KI) ,ECE=(BECFM=0,ELKSIZE=2056) 

Job SAMP492 in IMSVS. FFIKFJCE also shows an example of the JCL for this 
utility. 

CNLINI_FJC0VEBY - PRQCIPDFES 

The following recovery procedures can be used as a basis for the 
recovery procedures in jour installation. It is strongly recommended 
that you exercise ard enforce such procedures before going into a 
production phase with your online system. 

ASSUMPTIONS ADD EISIRICTICNS 

1. The same assumptions and restrictions described for the DL/I 
recovery procedures earlier in this chapter apply here as well. 

2. The recovery procedures outlined here for handling I/O errors on 
data bases involve closing down the online system, running batch 
recovery procedures, and then restarting the online system. 

Note: The above restriction is based solely on the subset approach, 
It is not an IMS/VS requirement that the online system be closed 
down to perform data base recovery. 

3. These procedures are designed to be used in conjunction with the 
JMS2VS_PrJLm€j;_Maste£_Terj^£^^ If you alter these 
procedures, you should ensure that tUe operating guide is changed 
accordingly. 

POSSIBLE FAILCBES 

The table in Figure 6-16 lists the most common failures, together with 
their symptoms, which can occur in the online system. For each failure 
an error class is given. This error class determines the required 
recovery procedures, which are outlined in Figure 6-17- 
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FAIL0BE/SITCA1ICN DESCEITICK 



| SYKFTOHS 



EBBOR 



1. OPERATING EBBCF 
1. 1 Cancel INS control region 
1.2 Cancel BHP 

2. APPLICATION FFCGBAB EFFCF 

2.1 MPF Abend 

2.2 EHF Abend 

3.IMS/VS EEEOF 

3.1 Abend 

3.2 Loop or wait state 

U.OS/VS EEBCE 
U.I Abend, loop or ncn-dispatcbable 

(storage dump taken) 
U. 3 Abend, loop or ncn-dispatcbable 
(Mo storage dump taken) 

5.HABDWABE EEROE 

5.1 Machine check, power failure 

5. 2 I/O Error on data base 

5.3 I/O Error on data base during 
backout 



X22 cr 00020 abend | £ 
X22 of EMP I A 



DFS555, EFS55U, DFS980 
DFS555,DFS554,DFS980 



IMS Abend code | B 

Cancelled (X22 or U0020) I B 

Ee-IFL | C 

Ee-IFL ! D 



Ee-IFL | D 

DFS451 ! E 

DFS96!,DFS983 ! F 



Note: Ihe IHS/VS control region may be canceled, either by 
an~OS/VS cancel command if it is running as a problem task, 
or by an 6s7vs~mgdif£~comBard if it is running as a system task. 

Figure 6-16. Possible Failures During An Online Session 

CORRECTING IHE CAUSE OF THE FAIIUFE 

This activity is completely dependent on the type of failure. The 
action, tc be taken by the master terminal operator (HTO) is outlined in 
the IHS/VS Primer HTOs Guide. 

EECOVEEY TASKS 

The subsequent recovery tasks to be performed for each defined error 
class are listed in Figure 6-17. The tasks must be executed free left 
to right. They are alsc described in flowchart form in the IHS/VS 
Primer HIO's Guide. 
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ERROR 
CLASS 


RECOVERY TASKS 


SHUT 
DOWN 
IMS 


CLOSE LOG TAPE 


CHANGE 
ACCUMULATION 


DATABASE 
RECOVERY 


BATCH 
BACKOUT 


RESTART 


NOTES 


DFSFLOTO 


DFSULTRO 


INCLUDE 
CURRENT LOG 


ONLY 
AFFECTED DS 


INCLUDE 
CURRENT LOG 


IMS 


BMP 


A 
















* 


1. 


B 














# 


* 


2,3,4 


C 




* 










* 


• 


2,3,4 









* 








* 


# 


2,3,4 


E 


* 






• 


# 




* 


» 


2,3,4 


F 


* 






• 


* 


* 


# 


* 


2,3,4,5 



Figure 6-17. Cata Ease Becovery Actions in an Online Environment 

Notes: 

1. Any updates done by an BEE or BME which has been cancelled, cr has 
arended, are automatically backed out by IHS/VS. 

2. If a BME or MPP is active at the time that the online system fails, 
the updates done by that application program are automatically 
tacked out during the emergency restart of IMS/VS. 

3. The BMP which was active at the time cf failure should be restarted 
from its last checkpoint. 

4. When the online system is restarted after a system failure, the 
terminal users should check the status of the transactions they 
entered immediately prior to the failure. Any special action they 
should take is documented in the operating procedures for that 
transaction in the IBS/VS Erimer Eemote Terminal Operators Guide. 

5. If during a system failure, the log buffer was lost (that is, log 
tape recovery was required) the subsequent restart may cause input 
messages to be lost (no data base updates done) or duplicate output 
messages (message retransmitted during restart). 

6. The progras named in the DFSS83 message must be specified in the JCL 
for the backout utility. 

It is important that these tasks be executed in the order shewn. Fcr 
example, if the system failed while a BME was active, the online system 
must be restarted after the other indicated procedures have teen 
followed. During restart, the BMP updates are backed out. Kext the EME 
should be restarted. If the BBE uses extended checkpoint/restart (XBST 
call) , you must supply the leg tape with the BMP checkpoint (the input 
log tape for the emergency restart) with the IBSICGB DD statement to the 
restart JCL. Since 0S/VS2 (BVS) enqueues on the volume serial 
information, you must first (MVS only) shut down the system in between. 
This oust be dene before any batch update programs are scheduled against 
the affected data cases. If desired, the system can be restarted, and 
then closed dewn as soon as the backout is complete. 

Note: There is an additional error situation which could occur if for 
some reason it is necessary tc recover a data base, and the log tape 
from the most recent online session is unavailable. For example, there 
cculd be an I/C error on the data base and the log tape from the last 
session has been lest due tc an operational error. 
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In this case, all data sets used in that online session must be 
recovered to the start of the online session during whicb the error 
occurred. £11 BNPs which update data bases, and vhich were run during 
that session must be re-run, and the remote terminal operators must 
re-submit all update transactions entered during that session. You can 
limit the above tc a single application if the data base in error is 
only used by that single application. If so, you must ensure that you 
recover ajl data bases used by that application, and conversely that the 
EMEs and update transacticts that are re-submitted affect only those 
data bases that are being recovered. 

Although this situation should not occur frequently, if at all, as it is 
a result of a combination of errors, it is nevertheless possible, and 
should be taken into acccunt when the application design is done. It 
may iiply that remote terminal operators must keep a hard-ccpy record cf 
the input to critical update transactions. 

LOG TAPE ADMINISTRA1ION IN AN ONLINE ENVIRONMENT 

The leg tape produced by the online IHS/VS system is vital for data base 
integrity. In addition it is also necessary for restarting the online 
system, and for providing statistics for monitoring the performance of 
the system. We will now discuss an administration scheme for 
controlling the log tapes used by the online system. Although this 
method dees not use generation data groups, ve will shov hov it 
interfaces with the sefceme fcr controlling batch log tapes that was 
described earlier in this chapter. 

l22-2JES_.E§£3-.Set_.Nam.€.s 

When a EBP is restarted, the leg tape ccntaining the checkpoint from 
which it is being restarted must be allocated via an //IMSLOGR DD card 
to the BMP partition. To avoid allocation conflicts some special tape 
handling technigues must be used. Although bypass label processing 
could be used in the BMP JCL, we recommend that standard labels be used 
for all jebs, but that the data set names be greater than seventeen 
characters. Ihis will avoid CS/VS allocation conflicts. 

The following JCL could be used: 

• Control Fegicn JCL 

//IEFRDER ED DSN*CNIINE. IMS. VS. PRIMER.LOG, .. . 

• EMP Restart JCL 

//IMSLOGR DE ESN-RESTARI.IMS.VS.PRIMER.LOG,.... 

This technigue could be extended further to other jobs which ycu may 
wish to run on the previous day's log tapes, while the online system is 
active. For example: 

• Log Tape Statistics 

//LOGIN ED DSN=STATS.IMS. VS. PRIMER. LOG,.... 

• Change Accumulation 

//DESULCG ED DSN= ACCOM. IMS. VS. PRIMER-LOG, .... ... 



jjo£e: This technigue is based en the fact that OS/VS enqueues on the 
full data set name in the DD card, but only the last seventeen 
characters are actually recorded on the tape label. 

Examples of the use of this caiing conventicn are shown in jobs SAMPI40, 
SAMFU74, SAMPU81 and SAMP455 in IMSVS.PRIMEJCB. 
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IfiS_l§£§_Sejjial_]iuiber.s 

To reduce the possibility of operator error, ve suggest that a pool of 
tapes be allocated for use as online log tapes, and that they b€ 
sequentially numbered, fcr example, LOG001, LOG002, LCG003,.. etc. By 
using seguential numbering, and using the tapes in sequence, the restart 
and change accumulation procedures are simplified. 

Re also suggest that log tapes be clearly marked as such with external 
labels, possibly in a bright color. This is to minimize the possiblity 
of an online leg tape being accidentally unloaded while the online 
system is active or being used by mistake as a scratch tape. 

Two forms are suggested. Cne is the IMS/VS Online log Sheet, 
(Figure 6-18) which is discussed in mere detail in Chapter 2 of the 
IMSZIS^Pjimer^Master^Tesiina^O^ The other is the Image 

Copy and Change Accumulation Form (Figure 6-1U) described earlier in 
this chapter. 

If you use generation data groups for maintaining your batch log tapes, 
two change accumulation jobs could be used: one for the log tapes 
produced by batch jobs, and one for those produced by the online system. 
All log tapes, batch or online must all be used in the correct time 
order to produce the change accumulation data sets needed for data base 
recovery. Examples are shewn in jobs //SAMP381 and //SAMP481 in 
IMSVS.PBIMIJOE. 

FREQUENCY OF IMAGE COPIES AND CHANGE ACCCMULATICNS 

The remarks made earlier in this chapter under this heading apply 
equally well to the online environment. 

The basic recommendation for change accumulation of the online log tapes 
is once a day. Another approach could be to perform change accumulation 
whenever the online system is terminated. However this approach could 
delay the restarting of the system, if the shutdown was unscheduled. 

Fetea£ion_Pe£iod_of_Online_£cs_laj)es 

The remarks made earlier in this chapter relating to batch log data sets 
apply egually to online log tapes. 
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IMS/VS ONLINE LOG SHEET 



/NRE 
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/ERE 
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DATE 



START 
TIME 



STOP 
TIME 



MTO 
NAME 



/CHE 


DUMPQ 


FREEZE 


OTHER 
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LAST 
CHKPT-ID 





LOG TAPES 


SERIAL 


CHANGE 
ACCUM 


STATS 



























TIME 



COMMENTS/INCIDENTS 



Figure 6-18, IMS/VS Online log Sheet 
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CHAPTER 7. INSTALLING IMS/VS 



This chapter contains detailed information necessary to install and use 
IMS/VS. 

Three different software installations are distinguished: 

• IMS/VS-DE installation 

• IMS/VS-ETAM installation 

• IMS/VS-VTAM installation 

In addition to the installation of IMS/VS itself, the generation of VTAM 
(level 2 only) and NCP/VS in our subset environment is also discussed. 

Eefore reading this chapter, you should be familiar with OS/VS and its 
system generation, and the access methods used by IMS/VS. IMS/VS 
operates under 0S/VS1 cr OS/VS2. Very little difference is experienced 
by the IMS/VS user between 0S/VS1 or 0S/VS2. The application programs 
are particularly unaware of the operating system being used. At this 
point we will consider only OS/VS1 in our discussion and examples. At 
the end of the chapter, additional considerations and guidelines are 
presented for the 0S/VS2 (MVS, cnly) user. 

The next section guides you through the installation process. 

IH1_I^STALLATI0N_PR0CESS 

The installation process for IMS/VS in an SNA environment consists of 
the following steps (see Figure 7-1). 

1. 0S/VS1 initial preparation- 

2« Creation of the IMS/VS libraries. 

3. Restoring the IMS/VS libraries. 

4. IMS/VS Stage 1 system definition. 

5. IKS/VS Stage 2 system definition. 
6.. CS/VS1 final preparation. 

7. VIAM and NCP/VS generation- 
Step 7 is not necessary for an IMS/VS-DE installation or a ETAM-only 
installation. 
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Figure 7-1. Installing IMS/VS 

0S/VS1 PEEPARATION 

Some 0S/V31 optional facilities are required to support IMS/VS, 
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OS£VS!_VSAK_Consid§raticns 

If VSAM is to be used for data bases, it must be included in 0S/VS1 
during system generation. Specify ACSMETH= (VSAM) in the 0S/VS1 system 
generation DATAMGT macro instruction, 

OS^VSJ_VTA«_Considerations_iDC_Only.). 

VTAM is incorporated into the operating system during operating system 
generation. In our subset, we will give an example of including VTAM in 
your operating system for use with IMS/VS. Details for planning and 
generating a complete 0S/VS1 and VTAM appear in: 

• £S^VS_System_Generation_Int£oduction, GC26-3790 

• QS^VSJ_System_Generaticn__Feference, GC26-3791 

• OS/VSJ_yTM-System_Proarammerls_Guide, GC27-6996 

VTAM is specified for inclusion in the operating system by using the 
ACSMETH parameter of the DATAMGT macro instruction: ACSMETH= (VTAM) . 
(The DATAMGT macro instruction is included in Stage 1 input to 0S/VS1 
system generation.) 

VTAM should run in a low-numbered partition (for high priority, 
normally, PO) - It should run at a higher priority than IMS/VS- The 
partition's size is determined by the user's needs. Information for 
estimating the size of the VTAM virtual storage partition appears in the 
OS/VS Storage Estimates manual. 

GTF: The generalized trace facility (GTF) must be installed and active 
to use the VTAM trace facility as discussed in Chapter 9 r 

"Optimization." 

IMS i /VS_Superyisor_Call_£outine 

One type 2 user SVC is required to execute IMS/VS, CB or DB/DC. This 
SVC must be defined in your OS/VS1 system during OS/VS 1 system 
generation. See "OS/VS 1 Systems Generation," SVCTABLE macro instruction 
for more details. 

An example of the SVCTABLE macro in your OS/VS1 system generation 
follows: 

SVCTABLE SVC-25U-E2-S0 

Normally, the SVC routine itself is not incorporated during the OS/VS1 
generation. So you must include a "dummy" load module in the BESMCDS 
partitioned data set. This should be done prior to Stage 2 of the 
OS/VS 1 system generation. 

The format of the module is: 

IGCnnn CSECT 
BR 1*1 
END 

where nnn is the unigue SVC number. This effectively NOPs the SVC 
number. The actual inclusion of the SVC routine in OS/VS1 will be done 
after the IMS/VS Stage 2 generation. 
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2E£i2H§i_PE29£anj_Products 

Additional program products are desirable but not required, such as: 

• PL/I optimizer compiler 

• OS/VS COBOL 

• Sort/Merge 

• Assembler H 

Note: A Sort/Merge function is required if using logical relationships 
or secondary indices, or the DL/I log data set change accumulation 
utility. 

INSTALLING A DB SYSTEM OR A DB/DC SYSTEM 

In the following sections, we will discuss the IMS/VS-DB and the 
IMS/VS-DB/DC installation separately, 

DB-only users should read the following section "Installing IMS/VS-DB" 
and then turn to the section entitled "Executing the Sample." 

DB/DC users should turn now to the section entitled "Installing 
IMS/VS-DB/DC." 

IMSTALLING_IMS^VS_2DB 

After the initial preparation of the 0S/VS1 system described in the 
preceding section, the following steps should be performed. 

CREATING THE IMS/VS-DB LIBRARIES 

Operation of IMS/VS-DB requires three categories of libraries for 
storing modules, programs and control blocks. 

The_IMS^VS2^_Distribution_Libraries 

The distribution tape from the IBM program library contains three 
libraries. 

• IMS.DBGENLIB contains the macros for the generation and execution of 
IMS/VS-DB. 

• IMS.DBLOAD contains the IMS/VS-DB load modules. 

• IMS.DBSOURCE contains the source code of the IMS/VS-DB modules. 

You should pre-allocate space for these libraries on your IMS/VS system 
pack and use IEBCOPY to restore them from the distribution tape. 

Notes: 

1. The IMS.DBGENLIB (named IMSVS.GENLIB when restored) is used only 
during IMS/VS system definition, Stages 1 and 2. After this, it is 
required only for system maintenance. 

2. The IMS.DBLOAD (named IMSVS.LOAD when restored) and IMS.DBSOORCE 
(named IMSVS.DBSOORCS when restored), are used only during Stage 2 
of IMS/VS system definition. After this, they are required only for 
system maintenance. 
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I!l§_IMS^VS-pE_S2steB_Libraries 

For the execution of IMS/VS-DB, the following system libraries are 

needed: 

• IMSVS.MACLIB contains the macros for the generation of DBDs and 
PSEs. 

• IHSVS.RESLIB contains the IMS/VS-DB execution modules. 

• IMSVS.PRCCLIB contains the IMS/VS-DE job control procedures. 

The MACLIE, RESLIB, and PRCCIIB are established during IMS/VS-DB 
generation, 

The_IMS/VS-DJ_A££lication_Litraries 

The following application libraries are needed for the execution of 
IMS/VS-DB application programs: 

• IMSVS.DBDLIB contains the DBDs. 

• IMSVS.PSELIB contains the PSBs. 

• IMSVS.PGMLIB contains the application programs. 

The DBDs and PSBs are stored as standard OS/VS load modules during DBD 
and PSB generation, respectively. The application programs are stored 
in the PGMLIE during link-editing. 

The_IMS^VS;DE_Primer_Functic^ 

The following sample libraries are created after restoring the IMS/vs-DE 
distribution tape: 

• IMSVS.PFIMESRC contains the sample source statement for the Primer 
function programs, DBD»s, PSB's, data base data, etc. 

• IMSVS.PRIMEJOB contains the JCL statements for the Primer function 
sample jobs. 

RESTORING THE IMS/VS-DB DISTRIBUTION LIBRARIES 

The IMS/VS-DB distribution tape contains three libraries which are 
unloaded partitioned data sets in IEBCOPY format. 

Notes: 

1. For the exact format you should check the distribution letter which 
accompanies the tape. 

2. Optionally, you will also receive a "PTF tape". This tape contains 
updated members of the original libraries. This tape should be 
restored first and merged with the original tape. 

IMS/VS-DB STAGE 1 SYSTEM DEFINITION 

Three IMS/VS system definition macros are used for the definition of an 
IMS/VS-DE environment. 
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The coding conventions for these macros are the same as for the coding 
of OS/VS Assembler language source statements. Processing of those 
macros by the OS/VS Assembler or the OS/VS program product Assembler H 
creates the input job stream for the execution of Stage 2. All the 
macros needed for the Stage 1 assembly are provided in IMSVS.GENLIB. 

Coding, the IMS/VS-DE System Definition Macros 

The three system definition macros reguired for the batch system are 
IMSCTRL, IMSCTF and INSGEN. They should be coded in that order as 
follows: 



/ < 



/ 



IMSCTRL I SYSTEM* (JvSlVJ, BATCH, f6.0)) 

JVS/2J {3.7j 

, MCS= (number[ , number, - - . ]) 

[ ,DESC=number ] 
t — .--.--.-.--.-------.-...--.,..-- — -.,-., j 

Optional operands: 

SYSTEM* specifies the OS/VS version and release, and the type of IMS/VS 

system to be generated- VS 1V with 6.0 specifies OS/VS1 Release 6.0. 

VS/2 with 3.7 specifies 0S/VS2 Release 3.7. BATCH specifies the 

generation of an IMS/VS batch system. 

MCS= specifies the VS routing code to be assigned to the IMS/VS system 
console if multiple console support (MCS) is included in the 
operating system. If MCS is not specified, no routing code is used. 
For a list of valid routing and descriptor codes see, OS/VS 
Sujaer visor Services and Macro Instructions, GC27-6979. 

DESC= specifies the message descriptor code to be assigned to the IMS/VS 
system console messages if MCS support is included in the OS/VS 
generations. If DESC is not specified, no descriptor is assigned. 

The MCS= and DESC= keywords should be defined as required for the 
ROOTCCE and DESC keywords of the OS/VS WTO macro. See the OS/VS 
Su£er,visor Services and Macro Instructions, GC27-6979, for a 
detailed description of the WTO macro keyword parameters. 

/ T 

IMSCTF |SVCNO=(,type2) 

,L0G=(SNGL, MONITOR) 
t — .* .-,-.j 

Optional operands: 

SVCNO= Specifies the operating system type 2 SVC number reserved for use 
by IMS/VS. Values entered may range from 128 to 255. The SVC 
number must be specified as the second parameter to be compatible 
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with earlier releases of IMS/VS; therefore, the parentheses and the 
comma are required. The default is SVCNO- (, 254) • 

LOG={SNGL, MONITOR) 

Should be coded as shown in our subset. It provides for one log 
data set per job (step) and the optional activation of the DB 
Monitor. 



/ "« 



IMSGEN 



JCL= ( TjIMSGEN 



Ijobname 



[ , job accounting] 



[". L — ihs n r. ( * n 

L (programmer name] J |_ (outputclassj 



f , (job miscellaneous) ]) 



[, NODE* (IMSVS, IMSVS, IMSVS)] 
[ nodeT node2 node3 J 



[• 



OBJDSET = 



IfiSVSiOB^pSET)] 
name JJ 



|",USEPLIB= (IMSVS -FESLIB 
|_. { name 



[•"iPfl 



L----- ................................................ ...........J 



JCL= 

jobname specifies a maximum of six alphameric characters to be used 
as the first portion of the generated job names. The last two 
characters of the job names are the internally generated, 
sequentially incremented, numeric values representing the 
relative position of each job in the Stage 2 stream. The 
default is IMSGEN. 

jobaccounting specifies job accounting data to be placed in the 

Stage 2 JCL. The length of the accounting data may not exceed 
50 bytes. 

programmername specifies the programmer name to be placed in the 
Stage 2 JCL. The default is IMS. 

outputclass specifies the output class to be generated for the Stage 
2 JCL. The default is A. 

job miscellaneous specifies any additional parameters the user may 

desire to have placed in the Stage 2 JOB statements. Length of 
this parameter cannot exceed 50 bytes. Recommended: 
TYPR0N=H0LD. 
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Note: If job accounting, programmer name or job miscellaneous 
contains non-alphabetic characters then the parameter should be 
enclosed in double quotes: »' *•. 



NODE= 



nodel specifies the node to be assigned to all IMS/VS data set names 
to be used and generated by IMS/VS system definition. The specified 
node can consist of from 1 to 8 characters. The first character 
must be a letter or a national character (3, $ # #) - The default 
node generated is IMSVS. 

node2 specifies the node to be assigned to the IMS/VS data set names 
MACLIB, PROCLIB, TUTRIX, JOBS, and RESLIB. This node overrides the 
nodel assignment for these specific data sets. 

node3 specifies the node to be assigned to the IMS/VS data set names 
DBSOURCS, 3ENLIB, and LOAD. This node overrides the nodel 
assignments for these specific data sets. 



OBJDSET= 



specifies the name (maximum of 24 characters) of a cataloged 
partitioned data set into which assembler object modules are placed 
during Stage 2 of IMS/VS system definition. The default is 
IMSVS-03JDSET. 



OSERLIB= 



specifies the name {maximum of 24 characters) of a library for usar 
modules to be included in the system. This is not applicable to 
IMS/VS-DB. However, to avoid JCL errors in Stage 2, you should 
specify here the name of your RESLIB if it is not IMSVS. RESLIB. 

ASM= 

specifies whether the OS/VS Assembler (VS) or OS/VS program product 
Assembler H (H) JCL is to be produced for the Stage 2 assembly 
steps. The default is VS. 

The IMS/VS Stage 1 system definition is a standard OS/VS assembly. The 
generated output is the Stage 2 job stream. 

IMS/VS-DB STAGE 2 SYSTEM DEFINITION 

This is the execution of the jobs generated by the Stage 1 system 
definition. 

0S/VS1 FINAL PREPARATION 

Some changes must be incorporated in 0S/VS1 after the IMS/VS-DB Stage 2 
system definition. 

ReiiUlL the OS^VS Nucleus with the IMS/VS Ty,p.e 2 SVC 

The OS/VS nucleus must be re-linked to include the Type 2 IMS/VS SVC 
module. This module was placed in IMSVS. RESLIB during Stage 2 of the 
IMS/VS system definition. 
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CoEX_!MSBDB_Proc€dur€_tg_SYS! = .PRgCLIB 

To be able to use the IMS/VS supplied procedures in IMSVS. PROCLIB, the 
IMSRDR procedure should be copied from IMSVS. PROCLIB to SYS 1. PROCLIB, or 
you should add IMSVS.PEOCLIB to the IEFPDSI DD statement of your CS/VS 
reader procedure. 

35S^yS-DE_INSTALIATION_JOBS 

This section presents all the jobs to install IMS/VS-DB,, A listing of 
these jobs is provided in Chapter 2 of the IMS/VS Pr.ime.r. Sample 
Listings. All jobs for the installation are named "SAMFInn", except the 
jobs generated by the IMS/VS-DB Stage 1, system definition. These are 
named "SAMPGnn". Most jobs are re-executable to allow easy installation 
of a new release of IMS/VS. All the referenced jobs are distributed 
with the IMS/VS system. The first five jobs, SAMPI01, SAMPI02, SAMPI05, 
SAMPI07, and SAMPI08, must be initially punched because they format and 
relcad the distribution libraries. 

After the tape libraries are restored, all the sample jobs are contained 
in IMSVS. PRIMEJOE. The source code for programs, PSBs, DBDs, etc. are 
available in IMSVS. PRIMESRC. 

U2ii : Unless otherwise stated, all these jobs should complete with a 
return code cf zero for a proper IMS/VS-DE installation- 

SAMPI01: PREPARE DISK VOLUME 

This job creates a SYSCTLG en the IMSPRM disk volume and constructs an 
IMSVS CVCL pointer and index structure. 

SAMPI02: ALLOCATE DISTRIBUTION LIEFABIES 

This job allocates space for the IMS/VS-DB distribution libraries and 
the Primer function sample libraries. 

SAMPI05: RESTORE PTF IIERSBIES 

This optional job restores the libraries from a PTF tape, if any. A PTF 
tape contains updated versions of IMS/VS modules. If a PTF tape is 
available, it must be restored first. 

SAMPI07: RESTORE IMS/VS-DE LIBRARIES 

This job restores the libraries from the IMS/VS distribution tape. 

SAMPI08: COPY PRIMER FUNCTION SAMPLE SOURCE AND JOBS 

This job copies the Primer function sample source and JCL statements 
from the distribution libraries to their execution libraries. 

The reader procedure (PRIME) in Figure 7-2 can be placed in 
SYS1. PROCLIB, to be used for reading in the sample jobs. 

//PRIME PROC JOB=TEMPNAME,DSN=«IMSVS. PRIMEJOE' 

//IEFPRCC EXEC FGM=IEFVMA, 

// PARM=*C06CC300005C11EOOC11AOO» 

//IEFRDFR T>V DS K=SDS N. (SJOB) , DISP=SHR, DCB=BUFNO= 1 

//IEFPDSI DD DSN=IMSVS. PROCLIB, DISP=SHR 

// DI DSN=SYS1. PROCLIB, DISP=SHR 

Figure 7-2- The ERIME Reader Procedure 
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The start command to be used with this reader is for example: 

S PRIME, JOB=SAMPI 15 

Note: The reader procedure of Figure 7-2 is for 0S/VS1 Release 6. You 
should verify its parameters with the standard reader procedures in your 
SYS1.PF0CLIB. 

SAMPI15: ALLOCATE IMS/VS-DB APPLICATION LIBRARIES 

This job allocates the IMS/VS-DB application libraries (DBDLIB, PSBLIB, 
and PGMLIB) . 

SAMPI17: ALLOCATE IMS/VS-DB SYSTEM LIBRARIES 

This job allocates the libraries for the actual IMS/VS-DB system 
definition (RESLIB, PROCLIB, OBJDSET, and MACLIB. ) 

SAMPI21: EXECUTE IMS/VS-DB SYSTEM DEFINITION STAGE 1 

This is an assembly job which generates the IMS/VS-DB Stage 2 system 
definition job stream. It needs only the macros in IMSVS.GENLIB. The 
output it produces can be punched into cards or placed on a direct 
access volume as a sequential data set or a member of a library- In our 
sample environment, we 'will place the generated job stream in the 
IMSVS. PRIMEJOB library, with a member name of STAGE2. 

Note: This assembly requires a large virtual partition when using the 
OS/VS system assembler. 2M bytes should be sufficient. 

SAMPG1 THROUGH SAMPG6: STAGE 2 JOBS 

These jobs perform the actual IMS/VS-DB system definition. They must be 
executed in numerical sequence. 

Notes: 

1. These jobs are not listed in Chapter 2 of the 

IHsl^VS Primer Source Listings. They are created as one member (STAGE2) 
as a result of job SAMPI21. 

2- Jobs SAMPG2, SAMPG3, and SAMPG5 need the 0S/VS1 system generation 
macro library SYS1. AMODGEN. This library should have a blocksize 
not larger than SYS1. MACLIB, because it is concatenated in the 
assembler SYSLIE DD statement. It must be cataloged. 

3. Control blocks and source modules processed during the execution of 
the Stage 2 job stream are assembled and link-edited into 

IMSVS. OBJDSET. Because these modules are link-edited individually, 
many will produce occurrences of the linkage editor message IEW046I 
(unresolved external reference) and set condition code U. These 
references are resolved later during the linkage editor steps that 
create the load modules in IMSVS. RESLIB. 

4. Job SAMPG6 can have a return code of 4 and message IEW0U6I will be 
issued for modules DFSIWAIT and DFSIOSUO when link-editing module 
DFSVC000 into IMSVS. RESLIB. This is a valid condition. 

5. The Stage 2 jobs can be read in with the PRIME reader procedure of 
Figure 7-2. 
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SAMFI25: RELINK OS/VS NUCLEUS WITH IMS SVC 

This job relinks the OS/VS nucleus to include the IMS/VS Type 2 SVC 
placed into IMSVS.RESLIB during Stage 2. Your OS/VS system programmer 
should check the linkage edit control cards to ensure that they comply 
with other installation requirements. Note that this job relinks the 
nucleus under the name IEANUlog. When you re-IPL the system after 
completing all the installation steps, you must specify this suffix (9) 
to lead the alternate nucleus. 

SAMPT35: RENAME THE IMS OS/VS NUCLEUS TO MAIN NUCLEUS 

After you have re-IPLed your system with the alternate nucleus linked in 
SAMPI25, and tested it, you may wish to rename this nucleus to IEANUC0 1. 
This job will perform the rename, after saving your original nucleus 
under the name IEANUCOF. 

You should now turn to the section "EXECUTING THE SAMPLE." 

INST ALL ING_IMS/VS_DB/DC 

After the initial OS/VS preparation the following steps should be 
performed. 

CREATING THE IMS/VS LIERARIES 

Operation of IMS/VS requires four categories of libraries for storing 
modules, programs, and control blocks. 

The_IMS/VS_Distribution_Libraries 

Two distribution tapes are supplied to install IMS/VS DE/DC. The DE 
tape contains the following libraries: 

• IMS.DBGENLIB contains the macros for the generation and execution of 
an IMS/VS-tE systetr. 

• IMS.DBLOAD contains the IMS/VS-DB load modules. 

• IMS.DBSOURCE contains the source code of the IMS/VS-DB modules. 
The DC tape contains the following libraries: 

• IMS.ECGENLIB contains the macros for the generation and execution cf 

IMS/VS-DC. 

• IMS.DCLOAD contains the IMS/VS-DC load modules. 

• IMS.DCSOURCE contains the source code of the IMS/VS-DC modules. 

You should pre-allocate space for the following four IMS/VS distribution 
libraries: 

•• IMSVS.GENLIB to contain DBGENLIB and DCGENLIB. 

• IMSVS.LCAD to contain EB10AE and DCLOAD. 

• IMSVS.DBSOURCE to contain EBSCURCE. 

• IMSVS.DCSOURCE to contain DCSCURCE. 

The OS/VS utility IEBCOPY is then used to restore and merge the tapes. 
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No£e: The above distribution libraries are needed only during IMS/VS 
system definition and subsequent system maintenance. They are not used 
during normal IMS/VS application processing. 

IkSL IMS/VS Sam£le Libraries 

Two sample libraries are created after the reload of the distribution 
tape Is) : 

• IMSVS. PRIMESRC, contains all the sample sources used in this 
publication. 

• IMSVS. PRIMEJOB, contains all the sample jobs used in this 
publication. 

The_JM S^VS_Sy,stem_ Libraries 

For the execution of IMS/VS, the following system libraries are needed: 

IMSVS. MACLIB contains the macros for the generation of DBDs and 
PSBs. 

IMSVS. RESLIB contains the IMS/VS execution modules. 

IMSVS.PROCLIB contains the IMS/VS job control procedures. 

IMSVS. MATRIX contains the security tables and matrices. 

IMSVS.JOBS contains the JCL used to initiate the MPP region. 

The MACLIB, RESLIB, MATRIX, and PR0CLI3 are established during IMS/VS 
generation. You should modify the JCL in the IMSVS.PROCLIB member named 
IMSMSG as necessary to meet the requirements of your installation and 
store it in IMSVS.JOBS. 

The IMS/VS A £p_l ic a t i o n _L i b r a r i e s 

The following application libraries are needed for the execution of 
IMS/VS application programs: 

IMSVS. DBDLIB contains the DBDs. 

IMSVS. PSBLIB contains the PSBs. 

IMSVS. PGMLIB contains the application programs. 

IMSVS. ACBLIB contains the ACBs. 

IMSVS. FORMAT contains the MFS control blocks. 

IMSVS. REFER AL contains intermediate text copies of MFS control 
blocks. 

The DBDs and PSBs are stored as standard OS/VS load modules during DBD 
and PSB generation, respectively. The application programs are stored 
in the PGMLIB during link-editing. ACBLIB is built when the block 
builder utility invoked by the AC3GEN procedure is used to build 
application control blocks from your PSBs and DBDs- FORMAT and REFERAL 
are established by the MFS utility. 
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Tk£_J*JS^VSJ)nline_Data_Sets 

The following data sets are essential for the execution of the online 
system: 

IMSVS.QELKS contains message queue control blocks. 

IMSVS.SHMSG contains the short message queue. 

1MSVS.LGMSG contains the long message queue. 

IMSVS.RDS contains control records for IMS/VS restart. 

IMSVS.EELLCG contains wcrk records used for dynamic fcackout and 

restart. 

QBLKS, SHMSG, LGMSG, EDS and DBLLOG are built and maintained by the 
online ccntrol program. 

BESTOEING THE IMS/VS DTSTEIEUTICN LIBBABIES 

Each IMS/VS distribution tap€ contains three libraries which are 
unleaded partitioned data sets in IEBCOPY format. 

Notes: 

1. For the exact format you should check the distribution letter which 
accompanies the tapes. 

2. Optionally, you will also receive two "PTF tapes." These tapes 
contain updated members of the original libraries. These tapes 
should be restored first and merged with the original tapes. 

IMS/VS DB/DC STAGE 1 DEFINITION 

IMS/VS system definition macros are used to describe the features and 
options you require for your system- These macros are provided in 
IMSVS.GENLIE. 

The coding conventions for these macros are the same as for the CS/VS 
Assembler language. Processing of these macros by the OS/VS Assembler 
or the OS/VS program product Assembler H creates the job stream for the 
execution of Stage 2. 

The macros can be divided into three categories: 

• System Environment: To describe the basic control program options. 

• Data Base and Application: To describe your online data bases, 
application programs, and transactions. 

• Data Communication: Tc describe your data communications 
configuration. 

We will now discuss these macros by category. Full details of coding 
the individual macros are given later in the chapter. 
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This category of aacro statements describes the basic IMS/VS control 
program options- You use them to describe such things as: 

Library and message queue data sets. 

Message processing region information. 

Number and size of message queue buffers. 

Sizes of various buffer pools and work areas. 

IMS/VS interface with the Operating System, for example SVC number. 

JOB and SYSOUT classes of the Stage 2 job stream. 

The macros included in this category are: 

IMSCTRL Defines the basic control program options. 

MSGQUEUE Defines the characteristics of the three user message queue 
data sets. 

SPAREA Defines the maximum number and size of scratchpad areas for 
conversational transactions to be maintained by IMS/VS. 

BOFPOOLS Defines the/ main storage buffer pool sizes for use by the 
online control region. 

IMSCTP Defines additional options and system parameters. 

IMSGEN Defines the desired assembler and linkage editor data sets and 
output options. 

The macro statements in this category describe the data bases, 
application programs, and transactions that will be processed by your 
online system. 

The macros included in this category are: 

DATABASE Defines a data base that is to be used in the online system. 

APPLCTN Names the PSB of the application program that processes the 

transaction codes specified by the TRANSACT macros that follow. 

TRANSACT Names the transaction codes that are to be processed by the 
application program described in the preceding APPLCTN macro. 

You must specify the DBD name of each data base (except logical DBDs) to 
be used by the online system with the DATABASE macro statement. 

One APPLCTN macro statement should be provided for each message 
processing program (MPP) that is to be used in the online system. The 
APPLCTN statement is followed by one or more TRANSACT macro statements 
defining the transactions processed by the MPP. You should also provide 
an APPLCTN statement for each batch program that is to run as a batch 
messsage processing program (BMP). In our subset, APPLCTN macros that 
define BMPs are not followed by TRANSACT macros. 
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Note: If a data base or batch program will never be used by the online 
system, it is not necessary to define it in the Stage 1 definition. 
However, you may include DATABASE, APPLCTN, and TRANSACT macro 
statements for resources that are not currently available. For example, 
you may define the statements for an application that is not yet 
implemented. This will mean that programs for the new application can be 
run online as soon as they are ready, without having to re-do the system 
definition. Warning messages for these 'dummy 1 definitions will be 
issued when the online control region is initiated. 

Data_Cgmmunications_Macro_Statements 

These macro statements describe your IMS/VS data communication 
facilities. They define such things as: 

• General communications requirements 

• Communication line groups, lines, and terminals (BTAM only) 

• VIAM nodes (VTAM only) 

• IMS/VS logical terminals associated with the nodes and terminals 

Macros included in this category are -- VTAM only: 

COMM Specifies general communications requirements that are not 

associated with any particular terminal type. Prepare one and 
only one per IMS/VS system definition. 

TYPE Describes a group of VTAM nodes of the same terminal type. 

Prepare one for each terminal type that is part of your IMS/VS 

system. 

TERMINAL Provides the characteristics of a terminal node of the type 
specified in the preceding TYPE statement. Prepare one for 
each terminal node. 

NAME Provides logical terminal names of the node specified by the 
preceding TERMINAL statement. Prepare at least one for each 
terminal node. 

Macros included in this category are -- BTAM only: 

COMM Specifies general system attributes that are not associated 
with any particular terminal. 

LINEGRP Defines a group of lines of the same type over which the same 
type of terminal communicates. 

LINE Provides the address and/or characteristics of one line in the 
line group defined by the preceding LINEGRP statement. 

CTLUNIT Provides terminal control unit address and attributes. Prepare 
one for each control unit attached to the line specified by the 
preceding LINE statement. 

TERMINAL Provides physical terminal data. Prepare one for each physical 
terminal attached to the line specified by the preceding LINE 
statement. 

NAME Provides a logical terminal name for the physical terminal 
specified by the preceding TERMINAL statement. Prepare at 
least one for each physical terminal. 
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These rules and restrictions apply to all of the IMS/VS macro 
statements. Refer to them while naming your resources in each of the 
macro definitions. 

• Names cannot include a blank, comma, period, hyphen, or equal sign. 

• All PSB names must begin with an alphabetic character (A thru Z, #,$ 
and d.) 

• Logical terminal names and transaction codes must begin with an 
alphameric character (A thru Z, #, $, and 3, or thru 9) . 

• IMS/VS null words cannot be used as a resource name: FOB, TO, ON, 
AFTER, SECURITY and MODE. Also, resource names should not begin 
with DFS or IWTOR. 

• Each IMS/VS macro statement can appear in a system definition a 
limited number of times. Figure 7-3 shows for our subset, the 
maximum number of times for each statement. 

• IMS/VS command keywords and their synonyms cannot be used as 
resource names. Figure 7-U gives a list of command keywords and 
synonyms. 



MACRO STATEMENT 


MAXIMUM OCCURRENCES 


IMSCTRL 




IMSCTF 




SPAREA 




MSGQUEUE 




BUFPOOLS 




DATABASE 


5000 


APPLCTN 


5000 


TRANSACT 


5000 


COMM 


1 


LINEGRP 


255 


LINE 


1000 


CTLONIT 


1000 


TYPE 


5000 


TERMINAL 


5000 


NAME 


5000 


IMSGEN 


1 



I - — .... ................J 

Figure 7-3. Number of macro statements per system definition. 
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Keyword 


5IS2HI1 


ABDUMP 




ACTIVE 


A 


ALL 




AREA 




ASSIGNMENT 


ASMT 


BALGRP 


BALG 


BOILDQ 


BLDQS,BLDQ,BUILDQS 


CANCEL 




CHECKPOINT 


CHKPT,CHECKPT,CHKPOINT 


CLASS 


CLS 


CNS 




COMP 




COMPONENT 


COMPT 


CONVEESATION 


CONV 


CPRI 




DATABASE 


DATABASES,DB,DBS 


DBD 




DC 




DONE 




DUMPQ 


DUMPQS 


FORMAT 


FMT 


FPPROG 




FPREGION 


FPRGN 


FREEZE 




ICOMPT 




INPUT 




KEY 




LEVEL 




LINE 


LINES 


LINK 




LMCT 


LCT 


LOPEN 




LPRI 




LTERM 


LTERMS 


MODE 




MODULE 




MONITOR 


MON 


MSDBLOAD 




MSNAME 




MSPLINK 




NOBMP 




NOCOMP 




NODE 




NOFEOV 




NOPASSWORD 


NOPSWD 


NOSHUT 


NOS 


NOTERMINAL 


NOTERM,NOTER 


NOTRANCMDS 




NOTRDY 




NOUSER 




NPRI 




OPTION 




OUTPUT 




PARLIM 




PASSWORD 


PASS WORDS, PSWD,PSWDS 


PCH 




PDS 




PI 




PLMCT 


PLCT 



Figure 7-4 (Part 1 of 2) . IMS/VS Command Keywords and Their Synonyms 
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Sy.nony.rn 



PRTI 

PROGRAMS, PROG, PROGS, PGM, PGMS 



PTERMS 
QUEUES, Q,QS 



R EGIONS, REG, REGS, MSGREG,MSGREGS, MSGREGION, 

MSGREGIONS 

RTC 



SER,SERS, SERIALS 



K§y.wor.d 

POOL 

PRIORITY 

PROGRAM 

PRT 

PSB 

PTERM 

PURGE 

QUEUE 

RDR 

READY 

REGION 

RTCODE 

SEGNO 

SEGSIZE 

SERIAL 

SET 

SHUTDOWN 

SNAPQ 

STATUS 

SYSID 

TDS 

TERMINAL 

TRANAUTH 

TRANCMDS 

TRANSACTION 

UDS 

USER 

UVDL 

VID 

XKEY 

Figure 7-4 (Part 2 of 2) . IMS/VS Command Keywords and Their Synonyms 

Co4ilia-tfe§-INS^VS_Sistem_Def inition_Macros 

This section contains the detailed coding instructions for 

the individual macros. 

The macros in the system environment category are discussed first, 

followed by the data base and application macros, followed by 

the data communication macros. 



TERMINALS, TERM, TERMS, TER,TERS 

TRANS, TR AN, TRANSACTIONS, TRANCODE, TR ANCODES 
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IMSCTPL Macro 

This statement describes the basic IMS/VS control program options, 
the OS/VS environment, and the type of IMS/VS system definition 
to be performed. 



/ ■ 

IMSCTFL ! SYSTEH=((VS1V}, f ALL 1,(6. 0\) 

{VS/2J {KDCLEOSJ (3.7 

,MAXREGN= (2, 128R, A, A) 
,IMSID=imsid 

, MCS= {numbor[ , number ,. . . ])l 
[ ,EESC=number ] 

Operands: 

SYSTEM= Specifies the OS/VS system and release, and the type of IMS/VS 
system to be generated, VS1V,6.0 specifies 0S/VS1 Release 6-0, 
VS/2,3.7 specifies OS/VS2 Release 3.7. 

•ALL' should be specified for the first system definition that 
you do.. This will generate a system definition for a complete 
Cr/EC system. 

If you subsequently wish to change the specifications of your 
system, for example by, adding data bases, application 
programs, transactions, or terminals, you should code the 
sub-parameter •NUCLEUS 1 . This will generate a system 
definition for a new control program nucleus and control 
blocks™ 

MAXREGN= Specifies the maximum number of partitions supported by the 
IMS/VS online control program at any one time. The first 
sub ^parameter indicates the total number of MPP and BMP regions 
that can be active. The second, third, and fourth 
sub -parameters specify region size, job class, and job message 
class, and are used for generating the JCL for the message 
region™ In our subset the parameters should be coded as shown 
to comply with our recommendation for one MPP region and one 
BMP region. 

IMSID= May specify a 1- to 4-character alphameric identifier for the 
IMS/VS system. This identifier will be used as the IMS/VS 
subsystem identifier; it must not conflict with any sub-system 
identifiers defined to the VS1 or HVS system, including other 
IMS/VS systems, batch or online. The default is IMSA. This 
identifier is also used to relate messages which are routed to 
the OS/VS system console to the corresponding IMS/VS system. 
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MCS= Specifies the VS routing code to be assigned to the IMS/VS 

system console if multiple console support (MCS) is included in 
the operating system- If MCS is not specified, no routing code 
is used. For a list of valid routing and descriptor codes see 
Ss^VS_Sup,ervisor Services and Macro Instructions, GC27-6 979. 

DESC= Specifies the message descriptor code to be assigned to the 

IMS/VS system console messages if MCS support is included in 
the OS/VS generations. If DESC is not specified, no descriptor 
is assigned. 

The MCS= and EESC= keywords should be defined as required for the 
ROUTCEE and DISC keywords of the OS/VS KTO macro. See 
QS^VS_SuEervisor_Services_and__Bacro Instructions, GC27-6979, for a 
detailed description of the WTC macro keyword parameters, 

IMSCTF Macro 

This statement defines certain control program options and system 
parameters. 

/ T 

(IMSCTF ! SVCNO=(,type2) 

,CORE=(2, 16,2,2) 

f3330,2CU8) 
,TYICG= H3340, 1540>,4) 
(335C,2C48J 

f333C) 
,BBS= K33U0 >, 20U8,2) 

[3350J 

,LOG=(SNGL, MONITOR) 



Optional operands: 

SVCNO= Specifies the operating system SVC number reserved for use by 

the generated IMS/VS system- Values entered may range from 128 
to 255. The SVC number must be specified as the second 
parameter to be compatible with earlier releases of IMS/VS; 
therefore, the parentheses and the comma are required- Default 
is SVCNO=(,25U) . 

COEE= Specifies the amount of dynamic storage used by the exclusive 

control ENQOEUE/DEQDEUE routines. In our subset the parameters 
should be coded as shown- This provides a minumum amount of 
2K, which can fce incremented by 2K to a maximum of 16K in 
subpool 2- 

Note: You may need to increase these values if you intend to 
run BMFs with a high number of data base updates between 
checkpoint calls. 
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DYLCG= Specifics the device type, buffer size, and number of buffers 

(4) to be used by the dynamic logging facility. In our subset; 
if a 3350 device is used, code (3350, 2048, U) ; if a 3340 device 
is used, code (3340, 1540,4) , if a 3330 device is used, code 
(3330,2C48,4) . 

FDS= Specifies the device tape, buffer size, and numbers of buffers 
to be used for the restart data set. In our subset, a buffer 
size of 2046 and tvo buffers are recommended. 

LOG= Specifies the type cf logging to be done. In our subset the 
parameters should be coded as shewn. It provides for one log 
data set per job (step) and the optional activation of the DC 
Monitor. 

IMSGEN Macro 

This specifies the JCL requirements and assembler and linkage editor 
options for the Stage 2 job stream. It must be the last macro statement 
in the input deck. 



/ - - 



/ 



IMSGEN 



0CL= 



L=([|IHSGEK H [, 
[( jobnamejj 



job accounting] 



\.i us 11 r.{ — * — 11 

L jprogrammername JJ |_ (outputclassJJ 

[ , ( job miscellaneous) ]) 

[,NODE = (IMSVS, IMSVS, IMSVs] 
|_ nodeT node2 node3j 

[,OBJDSET= {iMSVSiOEJDSETll 
L 1 name JJ 



EBLIB= JIHSVS.BESLIBI 
name 



(",USEBLI 



IMSVSiEESLIB}"! 
name J J 



(..... . .-_---- ................ . ...... .....J 



JCL= 



jebname specifies a maximum of six alphameric characters to be used 
as the first portion of the generated job names. The last two 
characters of the job names are the internally generated, 
sequentially incremented, numeric values representing the 
relative position of each job in the Stage 2 stream. The 
default is IMSGEK. 

job accounting specifies job accounting data to be placed in the 

Stage 2 JCL. The length of the accounting data may not exceed 
50 bytes. 
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programmername specifies the programmer name to be placed in the 
Stage 2 JCL. The default is IMS, 

outputclass specifies the output class to be generated for the Stage 
2 JCL. The default is A. 

job miscellaneous specifies any additional parameters the user may 

desire to have placed in the Stage 2 JOB statements. Length of 
this parameter cannot exceed 50 bytes. Recommended: 
TYPRON=HOLD. 

Note: If job accounting, programmer name or job miscellaneous 
contains non-alphabetic characters then the parameter should be 
enclosed in double quotes: ,, .... ,, . 



NODE= 



nodel specifies the node to be assigned to all IMS/VS data set names 
to be used and generated by IMS/VS system definition. The specified 
node can consist of from 1 to 8 characters. The first character 
must be a letter or a national character (d, $, #) . The default 
node generated is IMSVS. 

node2 specifies the node to be assigned to the IMS/VS data set names 
MACLIB, PROCLIB, MATRIX, JOBS, and RESLIB. This node overrides the 
nodel assignment for these specific data sets. 

node3 specifies the node to be assigned to the IMS/VS data set names 
DBSOURCE, GENLIB, and LOAD. This node overrides the nodel 
assignments for these specific data sets. 



OBJDSET= 



specifies the name (maximum of 24 characters) of a cataloged 
partitioned data set into which assembler object modules are placed 
during Stage 2 of IMS/VS system definition. The default is 
IMSVS. OBJDSET. 



USERLIB= 



specified the name (maximum of 24 characters) of a library for user 
modules to be included in the system. This is not applicable to our 
subset. However, to avoid JCL errors in Stage 2, you should specify 
here the name of your RESLIB if it is not IMSVS. RESLIB. 



ASM= 



specifies whether the OS/VS Assembler (VS) or OS/VS program product 
Assembler H (H) JCL is to be produced for the Stage 2 assembly 
steps. The default is VS. 
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MSGQUEUE Macro 

This defines the characteristics of the three message queue data sets, 



/' 



/ 



I | f3330] f T3330}, T3330] 

|MSGQUEUE | DSETS= (< 334C >,< 334 >,< 3340 >) 
! | (3350J, [3350J, (3350J 



I ,FECING= (250, 1500) 

I 

I ,EUFFEFS= (10, 1500) 



Operands: 

DSETS= Specifies the device types on which the three message queue 
data sets will reside. (IMSVS.QBLKS, IMSVS.SHMSG, and 
IMSVS.LGMSG, respectively). The data sets need not all reside 
on the same device type. 

FECLNG= Specifies the logical record lengths for the short and long 
message queue data sets, respectively- In our subset the 
operand should be coded as shown. It provides for our longest 
output message segment of 1388 bytes, control information and 
spare space. 

BUFFEKS= Specifies the number of buffers allocated for message queue 

management, and the block size used by the three message queue 
data sets. In our subset the operand should be coded as shown. 

SPAFEA Macro 

This macro defines the maximum number and size of the scratchpad areas 
(SPAs) maintained by the system. 



! ! 

1 SPAFEA } C0FF= (number, 1300) 

! I 



COBE= Specifies the number and size of the main storage SPAs. The 

first sub-parameter, 'number', indicates the maximum number of 
SPAs. This determines the number cf conversations that can be 
active at any one time, and therefore the number of terminal 
users who can be using conversational transactions at any one 
time. Ihe second sub-parameter indicates the maximum size of 
the SPA. In cur subset, it should be specified as shown. 

EOFPOOLS Macro 

This macro specifies the default main storage buffer pool sizes. These 
sizes can be overridden at execution time via the PAFM field of the 
IMS/VS control region procedure. 
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PSB=12000 
,PSBW=U000 
,DMB=8000 
,DBASE=7000 
,GENERAL= 12000 
,FORMAT=18000 
,COMM=4000 
,FRS=40 



Operands: 

PSB= Specifies the size of the PSB control block pool. 

PSBW= Specifies the size of the PSB work area pool. 

DMB= Specifies the size of the DWB control block pool. 

DBASE= Specifies the size of the common data base buffer pool. This 

pool supplies buffers for all the data bases used in the IMS/VS 
control region or partition. 

GENERAL= Specifies the size of the general buffer pool used by the 
IMS/VS control program, for producing system messages in 
response to communication activity. 

F0RMAT= Specifies the size of the message format block pool. 

COMM = Specifies any space to be added to the value calculated during 
system definition for the communication line buffer pool. 

FRE- Specifies the number of fetch request elements used for loading 
MFS control blocks into the message format block pool. 

Note: In our subset the operands should be coded as shown for the 
initial installation of your system. However these operands can be 
changed as your installation increases in size. Chapter 9, 
"Optimization, " discusses how the usage of these pools should be 
monitored, and gives guidelines for optimizing their sizes. The values 
shown here will normally be sufficient for the first-time user. 

DATABASE Macro 

This macro is used to specify the data bases to be used by the online 
system. One DATABASE macro must be coded for every SHISAM and HDAM data 
base and two DATABASE macros should be coded for a HIDAH data base, one 
for the index DBD and one for the HIDAM DBD. One DATABASE macro should 
be included for each secondary index that refers to any data bases 
defined in other DATABASE macros. The DATABASE macro should not be used 
to describe logical DBDs. 
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/ - 

I ! 

DATABASE | [INDEX,] 

! 

| BESIEENT 

I 

1 ,EBD=dbdname 
! 

L-- ...... .._.--.-.-- .......... .....................J 



Operands: 

INDEX Indicates that this is a DATABASE statement for a HIDAM index 
or a secondary index. It is a positional parameter. 

PESIDENT Indicates that the control block created for this DATABASE 
statement should be made resident at system initialization 
time. You should select this performance option for all your 
production data bases. 

DBD= Specifies the name of a data base description block (DBD) , as 
created by the DBDGEN utility. 

APPLCTN Macro 

The APPLCTN macro is used to describe the application programs that are 

to be run under the control of the online system. One APPLCTN macro 

must be specifed for each program that is tc run in either an MFF or a 
BMP region. 



» APPLCTN 



[BESIDENT,] 

PSB=psfcname 

,PGHTYPE=J TP 
BATCH 



Operands: 

RESIDENT Indicates that the FSB associated with this application program 
is to be made resident at system initialization time. This is 
a positional parameter, which you should select for all your 
production programs. The referenced PSB must have been 
processed by the ACEGEN utility before the program can be used 
online. If this is net done a warning message will be issued 
when the online system is initialized. 

PSB= Specifies the name of the PSE associated with the application 
program being described- If PGMTYFE=TP, the PSB name must be 
the same as the prcgraf name. 

PGMTYPE= Specifies the application program characteristics. TF 

indicates that the program being described is to run in an MPP 
region, and will be scheduled by the online system when there 
are messages which it can process. EATCH indicates that the 
program will run in a BMP region, and will be scheduled by the 
operator. 
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Note: Although the APPLCTN macro describes a program, the program name 
itself is never explicitly defined. This is because it can be 
determined from the PSE name if PGMTYFE=TP, or from the PARM field in 
the JCL for the BMP if PGMTYPE=BATCH . (See the IMSBATCH procedure 
described later in this chapter.) 

TRANSACT Macro 

The TRANSACT macro is used cne or more times with an APPLCTN macro- 
Each one specifies a transaction code that can be processed by the 
application program defined in the immediately preceding APPLCTN macro. 




CCDE=transaction code 
,MSGTYPE= (SNGLSEG, RESPONSE) 
,PR0CLIM=(5, 30) 



|7lNQ0IRY= ( 



INQ0IRY=j NO 

(YES,NCBECOV) 



}] 



,MODE-SNGL 

,SEGSIZE=1388 

,SEGNO=10 

[ ,SPA=(13C0,CORE,FIXED) ] 



Operands: 

CCDE= Specifies the 1 to 6 character transaction code (alphameric). 

The code must begin with a letter or a number. Transaction 

codes and LTERM narces must be unique. (See the NAME macro 
later in this section.) 

MSGTYPE= Specifies number of segments in the input message for this 
transaction code, and whether it is a response-mode 
transaction. In our subset the operand should be coded as 
shown. This indicates that the input message contains only one 
segment, and that it is a response-mode transaction. 



EFOCLIM= Specifies the nunsber 
program can process 
CPU time (in seconds 
subset the operand s 
an application progr 
the same transaction 
CPU time to process 
message, the program 
issues a GU to the m 
messages for that tr 
This is to prevent o 
region for too long 
is to ensure that a 
has used 2C seconds 
region. 



of messages of this transaction code a 
in a single scheduling, and the amount of 
) allowed to process each message. In our 
hculd be coded as shown. This means that 
am could process up to five messages for 

code and would be allowed 30 seconds of 
each message. After processing the fifth 

would receive a , QC status code when it 
essage queue, even if there were more 
ansaction code waiting to be processed, 
ne program from occupying the message 
a period of time. The second sub-parameter 
program that loops will be trapped after it 
of CPU time and cancelled by the control 
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INQUIRY= Specifies whether this is an inquiry transaction or not. If it 
is an inquiry-only transaction you should specify 
(YES,NORECOV) . This means that the transaction will not be 
recovered during an emergency restart, that is r it must be 
re-entered after a restart. It also reduces the number of 
records written to the log data set. The default is NO, that 
is, an update transaction. 

MODE= Specifies when data base buffers are to be written to direct 
access. MODE=SNGL means that the buffers will be flushed upon 
each request by the application program for a new message, and 
that only the last message processed by a program will be 
re-processed during emergency restart. In our subset the 
parameter should always be specified as shown. 

SEGSIZE= Specifies the maximum size of an output segment inserted to the 
message queue by a program. In our subset the parameter should 
be specified as shown. 

SEGNO= Specifies the maximum number of segments a program can insert 
to the output message queue per input message. 

SPA= Indicates whether this transaction is a conversational one, and 
the size of the scratch pad area. If the transaction is not 
conversational, this parameter must be omitted. 
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COMM Statement 

The COMM statement is used to specify general communication attributes 
that are not associated with any particular terminal type. COMM is 
always required for terminal types supported by VTAM. 



/ 



RECANY= (number, size) , 

APPLID=IMS, 

SECCNT=3, 

OPTIONS^ (FORPSW,FORCTERM,TIMESTAMP,FMTMAST) , 

COPYLOG=ALL 




Operands: 

RECANY= This parameter is required, 
buffers. 



It defines the VTAM RECEIVE ANY 



number 

specifies the number of VTAH RECEIVE ANY buffers to be 
present in the IMS/VS system. A value of eight is 
normally sufficient for an entry installation. 



size 



specifies the size of the largest RECEIVE ANY buffer. 
This size roust be large enough to handle the maximum input 
that may be received from any VTAM-attached terminal. A 
value of U000 would generally accommodate a full screen 
input from a 3278 Model 4 display terminal. 
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APPLID 38 Specifies the name through which VTAM identifies the IMS/VS 

system as a VTAM application program. This parameter should be 
coded as shown and must be identical to the application name 
coded on the APPL statement defining IMS/VS within the VTAM 
application major node. 

SECCNT* Specifies the maximum number of terminal and/or password 

security violations that may occur per physical terminal before 

the master terminal operator is notified. In our subset the 

parameter should be coded as shown. 

OPTIONS* Specifies certain system options, and in our subset should be 
coded as shown. This will mean that terminal and password 
security will always be used by the online system, that any 
system message whose number lies in the range DFS001 to DFS300 
will have the time it was generated inserted in the message, 
and that IMS/VS-provided MFS support is to be used for the 
master terminal. 

COPYLOG= Specifies hardcopy of all eligible commands and responses on 
the secondary master terminal. All subset commands are eligible for 
hardcopy. 



TYPE Statement 

The TYPE statement is used to define terminals attached to IHS/VS 
through VTAM. It defines the beginning of a set of one or more 
communication terminal and logical terminal description statements, 
terminals must be of the same type. 



All 



/■ 



/ 



TYPE I ONITYPE*(3270[ , LOCAL ]) , 

! TYPE=3270-An,SIZE= (11, cc) , 

| FEAT=IGNORE, 

J OPTIONS=TRANRESP, 

I PTRSIZE=IGNORE 



Operand: 

UNITYPE= Specifies the terminal device type contained in this 

communication description set. In our sample environment, just 
code either (3270, LOCAL) for the locally or (3270) for the 
remotely attached 3270 terminal groups. 

In our subset, we limit ourselves to the following 3270 control 
units and their attached display/printers. 

3271 Model 1, 2, 11, or 12 

3272 Model 1 or 2 
327U Model 1B or 1C (BSC line protocol only) 

3275 Model 1 or 2 

3276 Model 1, 2, 3, or 4 (BSC line protocol only) 
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TYPE = 



Specifies the display screen size type in our subset. It 
should correspond with the SIZE= parameter as defined in the 
following table: 



Sc£een_Size 



TYPE = 



SIZE* 





-"_ 


_ ___ _ 


12x80 


327C-A1 


(12,80) 


2Ux80 


3270-A2 


(24, 80) 


32x80 


3270-A3 


(32,80) 


43x80 


327C-A4 


(U3,80) 


12x40 


3270-A6 


(12,40) 


6xU0 


3270-A5 


(6,40) 



SIZE = 



FEAT= 



Specifies the display screen size, 
parameter discussion. 



See the preceding TYPE= 



Specify as shewn in our subset. It causes IMS/VS to ignore any 
special features of the display terminals. 



OPTIONS^ Specify as shewn in our subset. It causes IMS/VS to place the 
terminal in response ncde whenever the transaction is defined 
as such. 

PTPSIZE= Specify as shewn in our subset. It allows IMS/VS to be 
independent of printer terminal Printline width. 

Note: If UNITYPE=327C, the sequence of the TERMINAL statements defines 
which printer terminal will be used for a remote copy operation 
requested at a remote display terminal. When a copy function is 
requested, IMS/VS selects a printer terminal only from the set defined 
immediately after the definition of that display terminal. The printer 
selection process starts with the first subsequent printer terminal 
(must be a remote) , and stops at the next ncn-printer terminal. 

The printer selected must be ready, and not busy. 

TEPMINAL Statement 

This statement defines terminal node characteristics. The NAME 
statements that follow a TEEKIKAl statement supply the logical terminal 
names that are associated with the node at system definition time. 



/ i 

I 

TERMINAL | NAME-ncdename 
| [ ,1^11 = 3264] 
I 

I 
t , j 



Operands: 

NAME= The specified name irust be the VTAM node name defined during 
VTAM/NCP generation. 

It is through this name that IMS/VS addresses the VTAM node 
defined within VTAE/NCE. The name must be one of the node 
names defined on a LOCAL, TERMINAL or L0 statement within the 
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VTAM 3270 local major node, the NCF major node BSC group and 
SDLC group definition, respectively, 

UNIT= Specify for 3270 printer terminals only in our subset- May be 
specified as shown for any 3270 printer terminal type (that is, 
3284, 3286, 3287, 3288, and 3289). 

M0DEL= Specify for 3270 printer terminals only in our subset- MODEL=1 
applies only to the 328U/3286 printers. All other printers 
should be specified with M0DEL=2. 

NAME Statement 

This statement defines a logical terminal name (LTERM) associated with a 
node- The presence of the keyword MASTER in the LTERM operand 
designates this logical terminal name as the primary master terminal. 
In our subset this must be a display terminal with a screen size of 1920 
characters. The presence of the keyword SECONDARY in the LTERM operand 
designates this logical terminal name as the secondary master terminal. 
In our subset a secondary master terminal must always be specified and 
it must be a 3270 printer. 



/ * -i 



I 

! NAME 



lterm-name ] 

1 (MTC, MASTER) 
IMTCPEI NT, SECONDARY)! 



L--------------------------------~ .-- J 



Operands: 

lterm-name Specifies a 1- to 8-character name of a logical terminal to 
be associated with the previously defined physical terminal. 
WTOR is an invalid name because this is the default LTERM-name 
for the system console. In our subset, the names MTC and 
MTOPRINT are assumed for the primary and secondary master 
terminals, respectively, and should be coded as shown on the 
NAME statements following the TERMINAL statements for these 
terminals. 



Note: A naming co 
for the names of 1 
name indicates the 
If printer termina 
in the MPP, the pr 
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nvention should be established in your installation 
ogical terminals. For example it may be useful if a 

department or person normally using that terminal. 
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inter terminal that is associated with a group of 

In our example the first character , L I designates an 
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s whether it is a display or printer terminal, and the 
as a sequence number. Thus a program receiving an 
from logical terminal LCEP1D01 can determine that the 

in the same department is LDEP1P0 1, and can alter the 
alternate FCB to that name with a CHNG call. 
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Coding the Data Communication Statements -- BTAM 

COMM Macro 

This macro is used to specify general communication requirements that 
are not associated with any particular terminal type. In our subset it 
is used to specify additional system options. 

/ i 

/ I ! 

| ! COMM |SECCNT=3, 

! | | CFTICNS= (FCBFSW,FOFCTEFM,TIMESTAMP,FMTMAST) , 

| | |COPYLOG=ALL 



Operands: 

SECCNT= Specifies the maximum number of terminal and/or password 

security violations per physical terminal before the master 
terminal operator is notified. In our subset the parameter 
should be coded as shown. 

CPTIONS= Specifies certain system options, and in our subset should be 
coded as shown. This will mean that terminal and password 
security will always be used by the online system, that any 
system message whose number lies in the range DFSO0 1 to DFS300 
will have the time it was generated inserted in the message, 
and that IMS/VS-provided MFS support is to be used for the 
master terminal. 

COPYLOG= Specifies hard copy of all eligible commands and responses on 
the secondary master terminal. All subset commands are 
eligible for hardccpy. 

LINEGFP Macro 

This defines the beginning of a set of macros that describe one or more 
lines of the same type to which are attached the same type of terminal. 

/ - -i 

/ ! ! 

| ILINEGB? |EENAfiE=ddname 

1 I I 

| I |,0NITYPE=(327C[ , LOCAL]) 

f I I 

I................................................................... 



Operands: 

DDNAME= Specifies a 1 to 8 character name that associates the generated 
DCB for this line group with the EE statement generated by the 
Stage 1 system definition in the JCL for the control region. 
The name must begin with an alphabetic character. The 
following names cannot be used as LINEGRP ddnames: DFSFESLIE, 
DUMP, IEFFDEF, IEFFDEF2, IMSACE, IMSDBL, IMSDILIB, IMSLOG, 
IMSLOGR, IMSLOGB2, IMSLOG2, IMSMON, IMSRDS, IMSSPA, IHSTFMT, 
LGMSG, MSDBDUMP, MSEEINIT, HSDBCP1, MSDBCP2, PRINTDD, PFOCLIB, 
MATRIX, JOBS, QB1KS, SHMSG and SYSODUMP. 
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UNITYPE= Specifies the terminal device type attached to the lines in 

this line group. In our subset only the terminal types shown 
are considered. If UNITYPE= (3270, LOCAL) is coded, only one 
LINE macro can be in the line group. UNITYPE=3270 indicates 
remote 3270 terminals, and more than one LINE statement can be 
included in the line group. In our subset, we limit ourselves 
to the following 3270 control units and their attached 
display/printers. 

• 3271 Model 1, 2, 11, or 12 

• 3272 Model 1 or 2 

• 3274 Model 1B or 1C (BSC line protocol only) 

• 3275 Model 1 or 2 

• 3276 Model 1, 2, 3, or 4 (BSC line protocol only) 

LINE Macro 

This macro describes the communication line itself. Each LINE macro 
must be followed by at least one TERMINAL macro. Only one LINE 
statement per line group is allowed if 0NITYPE= (3270, LOCAL) was 
specified on the LINEGRP macro statement. If there is more than one 
terminal attached to the line, there should be multiple TERMINAL macros 
following the LINE macro. 



/ 



LINE |[ADDR= CUU ] 

! 

|[B0FSIZE=384] 



Operands: 

ADDR- Specifies the address of the communication line as defined in 
the transmission control unit. It must be of the form •cuu*. 
It is used only to generate the DD statements in the procedure 
for the online control region that is generated by the Stage 1 
definition. It must not be coded if 0NITYPE= (3270, LOCAL) was 
specified on the LINEGRP macro for this LINE. 

BOFSIZE Specifies the maximum size of an input message on this line. 

It is only required if this macro is defining a line containing 
local 3270 display terminals. In our subset the basic 
recommendation is 384. 

CTL0NIT Macro 

This macro specifies the 3271 remote control unit characteristics. This 
statement must not precede any 3275 terminal definition on that line. 
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/ - 

I 

C1LUNIT | ArBE=hex byte 

I ( 
I ,KODEl= fl 

I 12 

I 
i- .............. ...... — ........... .... ........ — .......j 



Operands: 



RDDP= 



MODEL* 



Specifies the two-digit hexadecimal polling address of the 
3271, the 3274 Model 1C, or the 3276 Model 1, 2, 3, or U. Ihe 
address cf the ccntrol unit is assigned by the IBM customer 
engineer upon installation. Note that the IBM customer 
engineer assigns the selection address which must be converted 
to the polling address for specification in this macrc. 



Specifies the ccntrcl unit model number for a 3271. 
or 3276, you must specify M0DEL=2. 



For a 327U 



TERMINAL Macro 

This macro defines physical and logical terminal characteristics. The 
NAME macro statements that follow a TEEMINAL macro statement supply the 
logical terminal names that are associated with the physical terminal at 
system definition. 



/ - 



TERMINAL 



(cuu 
ADDR=<^ xx > 
[xxxxj 

[,TYPE=327C-An,SIZE= (11, cc) ] 

[,FEAI=IGNORE] 

[ ,OPTIONS=TEANRESP] 

[,MSGtEI=SYSINFO] 

(,UNII=3264] 
[,PTRSIZE=IGNORE] 



['"°" I= {J[ 



c- ........................................................ .......J 



Operands: 

ADBR= Specifies the physical terminal address. 

For 327C local terminals this address is used when generating 
the UNI1= parameter on the DD card in the JCL for the contrcl 
region. It must re of the form •cuu 1 . 



Installing IMS/VS 7.33 



Except for a 3275, the address must be specified as two 
hexadecimal digits specifying the terminal address of that 
terminal on its control unit. 

For a 3275 the address must be specified as four hexadecimal 
digits. The first two specify the control unit polling 
address, while the last two specify the terminal address (for 
example, ADDR=4040) . 

Note that the IBM customer engineer assigns the selection 
address when installing the 3275, and this address must be 
converted to a polling addresss for specification in this 
macro. 

Note: If 3275*s are intermixed on the same line as 3270 control units, 
their TERMINAL definition must preceed the CTLONIT statements within the 
same LINE. 

TYPE= Specifies the display screen size type in our subset. It 

should correspond with the SIZE= parameter as defined in the 
following table: 



Scr.een_Size 



TYPE= 



SIZE = 





__— __ 


— "• — — — 


12x80 


3270-A1 


(12,80) 


24x80 


3270-A2 


(24,80) 


32x80 


3270-A3 


(32,80) 


43x80 


3270-A4 


(43,80) 


12x40 


3270-A6 


(12,40) 


6x40 


3270-A5 


(6,40) 



This parameter may be specified for display terminals only. 

SIZE= Specifies the display screen size. See the preceding TYPE= 

parameter discussion. May be specified for display terminals 
only. 

FEAT= Specify as shown in our subset. It causes IMS/VS to ignore any 
special features of the display terminals. May be specified 
for display terminals only. 

0PTI0NS= Specify as shown in our subset. It causes IMS/VS to place the 
terminal in response mode whenever the transaction is defined 
as such. May be specified for display terminals only. 

MSGDEL= Specifies which message types IMS/VS should discard for this 
terminal. In our subset this parameter should be coded as 
shown for printer terminals, and should be omitted for display 
terminals. When coded as shown, this will specify that DFS059 
TERMINAL STARTED messages will not be sent to this terminal. 

UNIT= Specify only for 3270 printer terminals in our subset. May be 
specified as shown for any 3270 printer terminal type (that is, 
3284, 3286, 3287, 3288, and 3289) . 

MODEL= Specify only for 3270 printer terminals in our subset. MODEL=1 
applies only to the 3284/3286 printers. All other printers 
should be specified with M0DEL=2. 

PTRSIZE= Specify as shown in our subset. It allows IMS/VS to be 
independent of printer terminal printline width. May be 
specified for printer terminals only. 
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Note: TERMINAL statements for local printer terminals may not he within 
the same LINE statement as lccal display terminals, that is, they must 
have their own LINEGRP and LINE statement. 

NAME Macro 

This macro defines a logical terminal name (LTERM) associated with a 
physical terminal. The presence of the keyword MASTER in the LTERM 
operand designates this logical terminal name as the primary master 
terminal. In our subset this must be a 3270 display terminal with a 
screen size of 1920 characters. The presence of the keyword SECONDARY 
in the LTERM operand designates this logical terminal name as the 
secondary master terminal. In our subset a secondary master terminal 
must always be specified and it must be a 3270 printer. 



NAME | T lterm-name 
| <^ |KTC, MASTER) 
| ((MTOPRINT, SECONDARY) 
I 



Operands: 
lterm-name 



Specifies a 1- to 8-character name of a logical terminal 
to be associated with the previously defined physical 
terminal. WTOR is an invalid name because this is the 
default ITERE-name for the system console. In our subset, 
the names MTO and MTOPPINT are assumed for the primary and 
secondary master terminals, respectively, and should be 
coded as shewn on the NAME statements following the 
TERMINAL statements for these terminals. 



Note: A naming convention s 
for the names of logical ter 
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terminal. If printer termin 
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STRUCTURE OF THE STAGE 1 IKEUT DECK 



The IMS/VS Stage 1 system definition is a standard OS/VS assembly, 
generated output is the Stage 2 job stream. 



The 
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ExampJLe: 



//STAGE1 JOB (ACCTING) 

// EXEC assembler-procname,PARM=DECK 
//SYSLIB DD DSN=IMSVS.GENLIB,DISP=SHR 
//SYSIN DD * 
IMSCTRL 



Stage 1 macro statements 



IMSGEN 
END 



/* 



The sequence of macro statements in the input deck is as follows: 

• System Environment Macros IMSCTRL must be the first, and the 

others may follow in any sequence, 
except IMSGEN must be at the end of 
the input-deck. 

• Data Base and Application As many sets of DATABASE and 
Macros APPLCTN/TRANSACT statements as 

required. 

• Data Communications Macros The COMM macro must be the first of 

this category, followed by sets of 
LINEGRP, LINE, CTLUNIT, TERMINAL, and 
NAME statements if B^AM, or TYPE, 
TERMINAL, and NAME statements if VTAM. 

• System Environment Macro The IMSGEN statement must be the last 

macro in the deck. It should be 
followed by an Assembler END 
statement. 

Jobs //SAMPI22 and //SAMPI23 in IMS VS. PRIMEJOB show examples of IMS/VS 
Stage 1 input decks for BTAM and VTAM systems, respectively. 

IMS/VS STAGE 2 SYSTEM DEFINITION 

This is the execution of the jobs generated by the Stage 1 system 
definition. 

OS/VS1 FINAL PREPARATION 

Some changes must be incorporated in your 0S/VS1 system after the IMS/VS 
Stage 2 system definition. 

£o£y_IMSRDR_and_IMS_Procedures_t 

To be able to use the IMS/VS-supplied procedures in IMSVS. PROCLIB, the 
IMSRDR procedure should be copied from IMSVS .PROCLIB to SYS 1 .PROCLIB. 
The IMS procedure should also be copied to SYS1. PROCLIB from 
IMSVS. PROCLIB so that the online control program can be started from the 
system console as a system task. 
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l§2ij}JS_£he_0S^Vj_t}ucleus 

The OS/VS nucleus must be re-linked to include the Type 2 SVC module 
that was placed in IMSVS. FES1IB by Stage 2. 

Customize_IMS_Control_|e2ign_P£Ocedure 

In order to te able tc access your data bases via the online system you 
must include DD cards for them in the IMS procedure. If you are using 
VSAM data bases, you should also define which VSAM buffer pool 
specification and fixlist members in IMSVS. FBOCLIE you wish to use. 
This is done by specifiying the VSPEC and FIX parameters on the EXEC 
statement, 

a£^ate_DFHM00_Member_in_IMSVS.PROCLIB 

To use LTWA and VSAM data bases online, you must update member EISVSMOO 

in IMSVS. PFOCLIE. 

Create DFSFIXOO Member in IMSVS. FFCCLIB 

— — — — — — — — — — — — — — — — — — — — — — .*.— — — — — — — — — — — . — — — MM 

To assure a stable response time in an entry IMS/VS environment you 
should fix in real storage some of the IMS/VS control blocks, buffer 
pools, and nucleus. In our subset we include a basic recommendation for 
this fixlist in cur sauple jcb stream. This is done by adding the 
DFSFIXOO member to IMSVS. PECCIIE. 

y£^§.l§_lJQili^I_System_Security_Tables 

Before you can start up the IMS/VS CTL region for the first time, you 
must update the initial system security tables. See the IMS/VS Security 
Maintenance Utility, later in this chapter. 

UE^§te_IMSMSG_Prccedure 

Modify the JCL in the IMSMSG member of IMSVS. PBOCLIE to meet your 
requirements and store it in IMSVS. JOBS. If you intend to use our 
sample status code error handling routine (DFSOAEB) you must include the 
ED card for the error listing in the IMSMSG procedure. 

PL^I Optimizer Considerations 

Special care in organizing the PL/I modules will help to decrease 
response time for those IMS/VS MPPs which use the PL/I Optimizer. Some 
organization suggestions fcllcw: 

• Use several different program libraries, one for each region, 
putting only those modules reguired by the application in the 
library. Include in that library all supporting modules (such as the 
PL/I transient library modules). 

• Concatenate the PL/I library into the message region STEPLIB. 

• Put the required supporting modules in the link pack area. This is 
the recommended long-terB solution for a virtual environment. 

(Caution: Do not use the PI/I Optimizing Compiler for multi-tasking 
during link-editing. Do net use SYS1.PLITASK as a SYSLIB data set.) 
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After the 0S/VS1 final preparation has been completed, yoa must re-IPL 
the system so that the changes you have made become effective. Note: 
If you are not using VTAM with IMS/VS, you can skip the following 
sections on VTAM and NCP/VS installation. 

PREPARING VTAM 

In the following sections, we will limit ourselves to a brief overview 
of VTAM Level 2 preparation using sample jobs. This is not intended as 
a replacement of the QS^VS VTAM Sy§tem Pr.ogrammer.is Guide, To verify 
the exact level of VTAM or ACF/VTAM required to support your 3270 
configuration, consult the IMS/VS Program Directory, which accompanies 
your IMS/VS distribution tape. 

Creating the VTAM Libraries 

The operation of VTAM requires the following three libraries: 

1. SYS1.VTAMLIB contains VTAM modules, tables and routines. This data 
set is initially created during OS/VS1 system generation, when 
ACSMETH=(VTAM) is specified in the DATAMGMT macro instruction. 

2. SYS1.VTAMLST contains VTAM definition statements and start options. 

3. SYS1.VTAM0BJ contains resource definition table (FDT) segments for 
each activated major node. 

The first time a major node is activated at VTAM initialization or with 
the VARY command, the related definition statements in SYS1.VTAMLST are 
processed into SYS1. VTAMOBJ. If a major node is redefined, the member 
on SYS 1. VTAMOBJ must be deleted prior to activating the changed major 
node. In our subset, we will assure this by always deleting and 
reallocating SYS1. VTAMOBJ before applying any changes to SYS1 . VTAMLST. 

Defining ,VTAM. Start Options 

Start parameters establish conditions and facilities that are to be 
effective when VTAM is started. They are entered into SYS 1. VTAMLST as 
members of 80-character card-image records. These members are used by 
VTAM to determine which major nodes to activate at start-up time, which 
parameters to use concerning VTAM buffer sizes, etc. 

There are five members in our SYS1 .VTAMLST: 

• ATCSTR00 contains start parameters plus a pointer to ATCCON00 

• ATCCONO0, a list of major nodes (VTAM application programs, local 
terminal sets, or NCPs) VTAM must activate when started. Each major 
node is defined as a member and listed in ATCCON00. Those in our 
subset are: 

APPNODES, a list of VTAM application programs 

LO3270, a list of local 3270s to be controlled by VTAM 

NCP, the NCP source statements (only if 370X is used) . 

Note: Member ATCSTR00 specifies, in addition to general configuration 
parameters, the number, size, and threshold values of the various VTAM 
main storage pools. These values are based on our subset network. 
Chapter 9, "Optimization," provides guidelines for the optimization (in 
general, reduction) of these pools during initial operation. See the 
section "Monitoring VTAM Pools" in Chapter 9. 
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5§fiSiH9_I!!S^VS - tg_VTAM: At a minimum IMS/VS must be defined to vtam as 
an application minor node. Additional applications can re defined 
together with IMS/VS as one major node called APPNODES in our sample. 

Note: The label on the APPL statement for IMS/VS must be the same as 
that coded in the APPLID= parameter of the COMM macro statement within 
IMS/VS System Definition- See the section entitled "Coding the Data 
Communication statements- VTAM" earlier in this chapter. 

2§fiJSin3_the_Local_Netviork_to_VTAM: The local 3 270 display stations 
and/or printers are defined as minor nodes of the major node LC3270. 
Each local display station or printer is defined by a separate LOCAL 
statement as a minor node. These lccal miner nodes are then grouped 
into one local major node, IC3270. 

Note: For a given terminal, the label on the LOCAL statement must be 
the same as the node name ceded in the NAME parameter of the TERMINAL 
statement within IMS/VS Stage 1 system definition. See the section 
entitled "Ceding the Tata Communication Statements — VTAM" earlier in 
this chapter. 

DSfinia^^iJ^^Bemote^Network^tc^VTAM: The remote network itself is 
defined in the network control program (NCP) in the 370X. To allow VTAM 
access to this definition, the NCE source deck is filed in SYS1.VTAMLST 
as member "NCP". This center name must be defined as a major node to 
VTAM. 

VTAM is started by naming a cataloged procedure in the OS/VS START 
command. The procedure must te filed into SYS1.PRCCLIB by using 
IEBUPDTE. When starting VTAK, the first parameter of the START command 
must be the assigned procedure name concatenated with .Pnn, where nn 
specifies the numbered partition in which VTAM is to run, normally F0. 
For example, if the assigned procedure is NET and VTAM is to run in the 
partition numbered 00, the start command is: S NET.PO. 

Note: Since other OS/VS cemmands used to operate VTAM, for example, the 
VARY command, always refer to SET instead of the cataloged procedure 
name, it is recommended that ycu name the procedure NET. This will also 
comply with cur sample MTO guide. 

GENERATING THE NET«ORK CCNTBCI IFCGBAM/VS (NCP/VS) 

As for VTAM, we will give crly a brief overview and a simple example of 
the NCP/VS generation. Since an NCP is largely hardware and application 
dependent, you should refer to the IBM 220U and 3705 Control Prccjram 
Generation and Utilities Guide and Beference Manual, GC3 0-3008 for the 
actual generation of your NCP. 

Note: An NCF is not required if only a local network is used. 

Overview 

A network control program must be generated for each communication 
controller in the VTAM network. An NCP generated to control one 
communication controller will net work properly in another unless they 
and their remote terminal networks are identical. An NCP is defined in 
the form of a source program consisting entirely of NCP generation macro 
instructions. The information coded in these macro instructions 
includes characteristics of the remote terminals and options that affect 

Installing IMS/VS 7.39 



the functions performed by the NCP. The resulting source program is 
assembled and link-edited to produce two load modules which constitute 
the NCP. 

The following steps should be performed to create an NCP that is to run 
with VTAM in our subset environment. 

S§§t2£ifi9L-tiig«NCP_Distribution_Libraries 

Prior to the NCP generation, the NCP support package for OS/VS, 574U-BA2 
must be installed. The instructions in the Memorandum to Users describe 
the installation procedures for the basic material. The important files 
on the distribution tape for OS/VS 1 are: 

• An unloaded partitioned data set containing the Assembler, Loader, 
Dump, Dynamic Dump and Initial Test (SYS1.SSPLIB in our 
installation) 

• An unloaded partitioned data set containing the NCP/VS Stage 1 
System Generation macros which are reguired for NCP generation 
(SYSV.GEN3705 in our installation) 

• An unloaded partitioned data set containing the NCP/VS Stage 2 
Generation macros (SYS1. MAC3705 in our installation) 

• An unloaded partitioned data set containing the object modules 
reguired for Stage II NCP System Generation (SYS1 .OBJ3705 in our 
installation) 

See the Memorandum to Users for a complete description of the 
installation procedure. 

Creating_the_NCP_Data_Sets 

The following libraries are reguired for the generation and execution of 
the network control program: 

• SYS1.NCPM0DS is the NCP load module library. Its name must match 
the QUALIFY= and LOADLIB= parameters of the NCP BUILD statement. 

• SYS1.NCPDUMP will hold NCP dump records. 

• SYS1.NCPOBJ will hold the NCP generation Stage 2 output as input to 
the link-edit of the NCP. 

Defining u _the - Remote_Network_tq_VTAM 

The remote network is that part of the network which is maintained 
through a 370X. To define the remote network to VTAM, the NCP source 
deck is used. The information about NCP must be made available to VTAM. 
This is accomplished by filing the NCP source program in 80-byte card 
image form as a member of SYS1. VTAMLST. 

Note: The name of the member must be the same as coded in the NEWNAME= 
parameter of the BUILD statement (NCP source deck) . 

Iiit_NCP_Sgurce_Deck_into_SYSl i VTAMLST 

The NCP source deck, which constitutes the input for Stage 1 of NCP 
generation, must be made available to VTAM. 
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The NCP is first stored in SYS1.VTAMLST under the member name "NCP". 
This same member name, NCP, is defined as a major node to VTAM via 
member ATCCON00 in SYS1. VTAKIST- 

Note: The comments in our sample NCP identify NCP parameters which are 
likely to b€ different in ycur installation, and direct you to the 
appropriate reference manual. 

§lase_J_of_NCP_ Generation 

Stage 1 is an assembly job using the communications controller 
assembler, CWAXOC located in SYS1.SSPLIB. Its output is the Stage 2 job 
stream. 

§£age_2_of _NCF_Gen^ration 

Stage 2 uses the communications controller assembler to assemble the 
control tables and program ircdules that reguire conditional assemblies, 
and places the resultant object modules on SYS1.NCP0BJ. Stage 2 then 
link-edits these modules and ether preassembled modules (located on 
SYS 1.OBJ3705) into SYS 1.NCPM0DS. From this library the VTAM-provided 
leader leads the control program into the 370X. 

IMS/VSJ3B/DC_INSTR11AT!CN_0CES 

This section presents all the jobs to install IMS/VS DB/DC including 
VTAM and NCP/VS. A listing of these jobs is provided in Chapter 2 of 
the IMS/VS Primer Sample listings. All jobs for the installation are 
named~"SAMFInn7"~except""the jobs"~generated by the NCP/VS and IMS/VS 
Stage 1 system definition. These are named "SAMPNnn" and "SAMFGnn", 
respectively. Most jobs are re-executable to allow easy installation of 
new releases of IMS/VS. These jobs can be executed from the 
IMSVS,PFIMEJCB library, except the initial jobs: //SAMPI01, //SAMPI03, 
//SAMPI04, //SAMPI05, //SAMPI06, //SAMPI07, //SAMPI08, and //SAMPI09. 
The two latter ones create the sample IMSVS.PBIMEJOB and IMSVS. PEIMESBC 
libraries. The source code for programs, PSEs, DEDs, etc., is available 
in a library called IMSVS.PBIMESBC, after above mentioned initial jobs. 

Notes : 

1. Unless otherwise stated, all these jobs should complete with a 
return code of 2ero for a proper IMS/VS installation. General 
exceptions ar€ IEHPEOGM and IEBUPDTE jobsteps, and the link editor 
steps of the FL/I compilations. 

2. Jobs SAMFI6n should not be executed if only a local network is to be 
used. 

3. Jobs SAMPI5n and SAMPI6n should not be executed if ETAM is to be 
used. 

SAMPI01: PBEPAB1 DISK VOLUME 

This job creates a SYSCTLG on the IMSPBM disk volume and constructs an 
IMSVS CVCL pointer and index structure. 

SAMPI03: ALLCCAT1 DISTBIBUTICN LIBEAEIES 

This jot allocates space for the IMS/VS distribution libraries. 
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SAMPIOU: RESTORE LIBRARIES FROM DC PTF TAPE 

This optional job restores the libraries from the DC PTF tape, if any. 
A PTF tape contains updated versions of IMS/VS modules. If PTF tapes 
are available, they must be restored first. 

SAMPI05: RESTORE/MERGE LIBRARIES FROM DB PTF TAPE 

This optional job restores the libraries from the DB PTF tape. 

SAMPI06: RESTORE IMS/VS DC DISTRIBUTION LIBRARIES 

This job restores the libraries from the IMS/VS DC distribution tape. 

SAMPI07: RESTORE/MERGE IMS/VS DB DISTRIBUTION LIBRARIES 

This job restores and merges the libraries from the IMS/VS DB 
distribution tape. 

SAMPI08: COPY PRIMER FUNCTION DB SAMPLE SOURCE AND JOBS 

This job copies the Primer function DB sample source and JCL statements 
from the distribution libraries to their execution libraries. 

SAMPI09: COPY PRIMER FUNCTION DC SAMPLE SOURCE AND JOBS 

This job copies the Primer function DC sample source and JCL statements 
from the distribution libraries to their execution libraries. 

The reader procedure (PRIME) , in Figure 7-5, can be placed in 
SYS1.PR0CLIB, to be used for reading in the sample jobs. 

//PRIME PROC JOB=TEMPNAME,DSN=»IMSVS.PRIMEJOB» 

//IEFPROC EXEC PGM=IEFVMA, 

// PARM=»006 003 00005011E00 011AOO» 

//IEFRDER DD DSN=SDSN. (&JOB) , DISP=SHR, DCB=BUFNO= 1 

//IEFPDSI DD DSN=IMSVS. PROCLIB, DISP=SHR 

// DD DSN=SYS l.PROCLIB,DISP=SHR 

Figure 7-5. The PRIME Reader Procedure 

The start command to be used with this reader is for example: 

S PRIME, JOB=SAMPI 15 

Note: The reader procedure of Figure 7-5 is for 0S/VS1 Release 6. You 
should verify its parameters with the standard reader procedures in your 
SYS1.PR0CLIB. 

SAMPI15: ALLOCATE IMS/VS APPLICATION LIBRARIES-DB 

This job allocates the IMS/VS application libraries JDBDLIB, PSBLIB, and 
PGMLIB) . This job should be needed only the first time you install 
IMS/VS. 

SAMPI16: ALLOCATE IMS/VS-DC APPLICATION LIBRARIES 

This job allocates the application libraries used by the online IMS/VS 
control partition/region. This job should be needed only the first time 
you install the IMS/VS DC feature. 
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SAMPI17: ALLOCATE IMS/VS SYSTEM LIBBAEIES 

This job allocates the libraries for the IMS/VS system definition 
(PFOCLIE, MACLIB, RESLIB r and OBJDSET) . 

SAMPI18: ALLOCATE IMS/VS ONLINE DATA SETS 

This job allocates the IMS/VS system data sets used by the online system 
(QBLKS, SHMSG, LGMSG, EDS, KATEIX, JCBS, and DBLLOG) . 

Warning: If you reallocate the IMS/VS message queues and you decrease 
the queue data set size, you must subsequently do a cold start of the 
IMS/VS control region. Per a description of how to do a cold start, see 
Chart F-1 in the IMS/VS Primer Master Terminal Op.erator.ls Guide — VTAM. 

SAMPI23: EXECUTE IMS/VS SYSTEM DEFINITION STAGE 1 -- VTAM 

This is an assembly job which generates the IMS/VS Stage 2 system 
definition job stream- It only needs the macros in IMSVS. GENLIB- The 
output it produces can be punched into cards or placed on a direct 
access volume as a sequential data set or a member of a library. In our 
sample environment, we will place the generated job stream in the 
IMSVS. PRIMEJOE library, with a aember name of STAGE2. 

Note: This assembly requires a large virtual partition, when using the 
OS/VS system assembler. 2M bytes should be sufficient. 

Figure 7-6 gives an overview of our sample terminal network as specified 
in the IMS/VS Stage 1 input cf SAMPI23 and the associated VTAM and 
NCP/VS jobs cf the following sections. 
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IMS/VS PRIMER NETWORK 



NCP/VS 



MEMORY 144K 

CHANNEL ADAPTER TYPE 2 

COMMUNICATION SCANNER TYPE 2 

SUBAREA = 2 



BSC 
LINE 



2400 BPS 
FDX 



2400 BPS 
FDX 



LEGEND 



LTERM NAME 



OS/VS 



IMS 
CTL 



IMS 
MPP 



VTAM NODE 
SUBAREA 3 



LU=0 , 
LDE P2D01/ 



3286 



SD000271 



LU = 2 



LOCAL 3270-1 



LDEP3D027 



3286 



TO/LDEP0D01 



CHL00372 



422 , 
DEP1D02/ 



3286 



CHL00472 



IMS 
BMP 



Figure 7-6. Sample IMS/VS-VTAM Network 



SAMPI22: EXECUTE IMS/VS SYSTEM DEFINITION STAGE 1 -- BTAM 

This is the IMS/VS system definition Stage 1 job to be used instead of 
the previous job if you are using BTAM instead of VTAM. 

SAMPG1 THROUGH SAMPG19: STAGE 2 JOBS 

These jobs perform the actual IMS/VS system definition. They should be 
executed in numerical sequence. 



Note: 



These jobs are not listed in IMSVS. PRIMEJOB. They are created as 
one member (STAGE2) as a result of job SAMPI22 or SAMPI23. 

Jobs SAMPG4 through SAMPG11 need the OS/VS 1 system generation macro 
library SYS1 . AMODGEN. This library should have a blocksize not 
larger than SYS1.MACLIB, because it is concatenated in the assembler 
SYSLIB DD statement of some Stage 2 jobs. It must be cataloged. 

Control blocks and source modules processed during the execution of 
the Stage 2 job stream are assembled and link-edited into 
IMSVS. OBJDSET. Because these modules are link-edited individually, 
many will produce occurrences of the linkage editor message IEW0U6I 
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(unresolved external reference) and set condition code U. When 
these messages appear in listings, they should be considered noriral 
for the following FES1IE modules: 

EFSNOF10 control blccks module 1 

DFSNOF30 control blocks module 1 

DFSNEP10 control blocks module 2 

EFSNFP30 control blccks module 2 

DFSICPLO features option list control blocks 

EFSIELKO control blccks module U 

SAMPI24: COFY IMSBER ANE IMS PROCEDURES TO SYS1.FR0CLIB 

This jcb copies the IMSRDE procedure to SYS 1 .PROCLIB. The reader 
procedure provides access to the message region procedure in IMSVS. JOBS. 
You should adjust the parameters of the IMSRDR procedure to your 
installation standards- The IKS procedure is renamed IMSCTL and is the 
one used for executing the online control region. 

SAMPI25: RELINK OS/VS NOCLEOS KITH IMS SVC 

This job relinks the CS/VS nucleus to include the Type 2 SVC placed into 
IMSVS-RESLIP during Stage 2. Your OS/VS system programmer should check 
the linkage edit ccntrcl cards to ensure that they comply with other 
installation requirements. Note that this job relinks the nucleus under 
the name IEANUC09. When ycu re-IPI the system after completing all the 
installation steps, you must specify this suffix to load the alternate 
nucleus. 

SAMPI35: RENAME IMS OS/VS NUCLEUS TC MAIN NUCLEUS 

After you have re-IPLed ycur system with the alternate nucleus linked in 
SAMPI25, and tested it, you may wish to rename this nucleus to IEANUC0 1. 
This job will perform the rename, after saving your original nucleus 
under the name IEANUCOF. 

SAMPI40: UPDATE IMSCTI FECCEDDBE WITH SAMPLE EATAEASE JCL 

This job updates IMSCTI procedure created in job SAMPI2U to include the 
DD statements for the data bases used by the sample programs. It also 
overrides the EXEC statement parameters with our subset values. 

SAMPI41: UPDATE EUFFEE PCCI SPECIFICATION FOR THE ONLINE SYSTEM 

This job updates member DFSVSMOO in IMSVS. PROCLI B, with buffer pool 
specifications suitable for running the sample programs. 

SAMPI42: UPDATE IMSKSG EECCFDUEE WITH USER EE CARE 

This job updates IMSMSG procedure to include the ED card used by the 
status code error handling routine. 

SAMPT43: CREftTE FIXLIST CONTROL CARDS 

This job creates the DFSFIXCC member in IMSVS. PROCIIE. This member 
contains control statements for fixing parts of the IMS/VS control 
region in real storage. These specifications should be sufficient for an 
entry system. 

Note: No combination characters are allowed in the control cards of 
//SAMPIU3. 
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SAMPI45: SYSTEM SECURITY TABLES -- VTAM 

This job updates the initial system security tables- If necessary it 
can be modified to accommodate your own security requirements. At least 
you should change the password NONPRIME to your own password to secure 
the use of IMS/VS commands not included in our subset- This job must be 
executed prior to the initial start-up of the CTL region. 

SAMPI44: SYSTEM SECURITY TABLES -- BTAM 

This job is comparable to the previous one, SAMPI45, but it is suitable 
for a BTAM version of the IMS/VS system. The difference is in the 
logical terminal network and the command subset. 

Note: After the OS/VS final preparation has been completed, you must 
re-IPL the system so that the changes you have made become effective. 
This should be done after job SAMPI25 and before the initial start-up of 
the CTL region. 

SAMPI50: ALLOCATE SYS1.VTAMLST 

This job allocates space for SYS 1 . VTAMLST. 

SAMPI51: PROCEDURE FOR SYS1.VTAM0BJ 

This job adds a cataloged procedure named SAMPI51A to SYS1. PROCLIB. 
This procedure will be used to scratch and reallocate SYS1.VTAM0BJ in 
every job which updates SYS 1. VTAMLST. This ensures the synchronization 
of these libraries. 

SAMPI52: DEFINE IMS/VS TO VTAM 

This job adds the definition of IMS/VS as VTAM application to 
SYS 1. VTAMLST via member APPNODES. 

SAMPI53: DEFINE LOCAL NETWORK TO VTAM 

This job adds the definition of the local 3270 terminals to VTAM via 
member L03270 in SYS1. VTAMLST. In the sample job, only three local 3277 
Model 2 screens and two local 3286 Model 2 printers are defined. You 
can add additional ones by repeating the LOCAL statement. 

SAMPI54: FILE VTAM START PARAMETERS 

This job adds the VTAM start parameters, member ATCSTPO0, and the major 
node list, member ATCCON00, to SYS 1 .VTAMLST. 

Note: If only a local network is used, you should delete the NCP node 
name in the ATCCON00 list. And if only a remote network is used, you 
should delete the LO3270 node name in the ATCCON00 list. 

SAMPI55: FILE VTAM START PROCEDURE 

This job adds to SYS1. PROCLIB the procedure to be executed during VTAM 
start-up. 

Note: The NCPDUMP and NCPMODS DD statements are not required for a 
local-only network. 

SAMPI56: STORE GTF PROCEDURE FOR VTAM TRACES 

This job stores the GTF procedure for VTAM main storage pool traces into 
SYS1. PROCLIB. 
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SAMPI60: ALLOCATE NCF LIEBA5IES 

This job (re)allccates the libraries for NCP generation and execution. 
In addition the following NCP distribution libraries are required during 
NCP generation and roust be cataloged: 

• SYS1.SSP1IB 

• SYS1.GEN37C5 

• SYS1.MAC3705 

• SYS1.OEJ3705 

SAMPI61: FILE NCE SOUECE EICK 

This job files the NCF source deck into SYS1.VTAMLST as member NCP. 
This sample NCP must be adapted to your installation environment. 

SAMFI62: LIST NCP JOBCARD MACRO 

This job lists the macro JCECAED from the NCP generation Stage 1 macro 
library SYS1 .GEN3705. Stage 1 assembly provides job cards for the Stage 
2 NCP generation job stream. Ycu might have to change this macro 
statement for two reasons: 

1. Special account information needed in your OS/VS1 installation. 

2. The contents of litrary SYS1.SSPLIB as distributed with the NCP 
support package is not incorporated in SYS1.LINKIIB or concatenated 
to it as suggested. 

SAMFI63: CHANGE JCBCABD MACBC FOB NCP STAGE 2 

This job adds a JOB card tc the macro JCBCABD and changes the account 
information. A JCB1IE DC statement can be added to refer to SYS1.SSPLIB 
containing the communication controller assembler used for Stage 2 
assemblies. 

SAMPI6U: NCF GENERATION, STAGE 1 

This job is the Stage 1 of the NCF generation. It creates the Stage 2 
job stream and puts it into the partitioned data set IMSVS.PRIMEJOB 
under the name NCPSTG2. 

Note: The MAXDATA=2468 value in the PCCU macro of the NCP deck is based 
on a screen size of 1920 characters. If your installation includes 
larger screen sizes, you might need to increase this value. 

SAMFN1 THRCTJGH SAMFN16: NCP STAGE 2 JOES 

These jots perform the actual NCP generation. They must be executed in 
numerical seguence. Several NCP generation jobsteps may cause a 
condition code of 4. Check the issued warning messages. 

Note: These jobs are net listed in IHSVS. PEIHEJOB- They are created as 
one'member (NCPSTG2) as a result of job SAMPI6U. 

SAMPI65: CREATE LOGON MODE TABLE 

A logon mode table is required for 3270s using SDLC. This table should 
be constructed as shown in cur subset. 

SAMPI66: CREATE LOGON TABLE 

A VTAM logon table is required for 3270s using SDLC. This table should 
be constructed as shown in our subset in order to comply with our 
operating procedures. 
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EXECUTING THE IMS/VS PRIMER SAMPLE JOBS 

This section presents the sample jobs which can be executed after the 
installation of IMS/VS. These jobs are also included in IMSVS. PRIMEJOB, 
and listed in Chapter 2 of the IMS/VS Primer Sample Listings manual. 
The relevant output listings of selected sample jobs are contained in 
Chapter 3 of the IMS/VS Primer Sample Listings manual. 

The following groups are distinguished: 

Initialization jobs for the creation of the sample environment, 
phase 0. 

Phase 1 jobs, used in the Phase 1 environment. 

Phase 2 jobs, used in the Phase 2 environment. 

Phase 3 jobs, used in the Phase 3 environment. 

Phase 4 jobs, used in the Phase 4 environment. 

We recommend that you exercise these jobs in this sequence. 

He will now briefly discuss the job in each of the above sections. A 
more detailed discussion of the function of each job can be found in its 
originating chapter. 

Notes: 

1. The sample jobs are designed so that they can be re-executed in most 
cases. 

2. The jobs either contain all their input or refer to IMSVS. PRIMESRC 
for some input. 

3. Guidelines to exercise the sample batch application programs are 
given in their source code. 

4. The virtual storage requirement of each job (step) is less than 512K 
bytes unless specified in the region parameter of the execute 
statement. For more detailed information on IMS/VS storage 
requirements see: IMS/VS System Programming Reference Manual, 
Chapter 5, "IMS/VS Storage~EstImates. » ^ 

INITIALIZING THE SAMPLE ENVIRONMENT 

The following jobs in IMSVS. PRIMEJOB can be used for the initialization 
of the sample environment. 

S-MSP-OS i R§JS°.£® _ Sa J2£le_ VS A M _Use r _Ca t alog_a n d^Spac e 

This job can be used to remove all the VSAM data space for the sample. 

SAMP 006: Define _VS AM _User_Catalog 

This job defines a VSAM user catalog (IMSPRIME) on volume IMSPRM, used 
by the sample system. 

SAMP 00 7: Define_VSAM_Data_S£ace 

This job defines the VSAM data space for the sample data bases. 
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P. AHPOO 9 : Bu iia_G€n€r at ion_Data_G r cujgs 

This job builds the generation data groups and model DSCBs to t€ used 
for the image copy, monitor, and log data sets. 

PHASE JOES 

The following jobs assemble and link edit programs and DBDs of general 
use: 



• SAMP010 

• SAMF030 

• SAME031 

• SAMP032 

• SAMP033 

• SAMP034 
Notes: 



GSAM DBDs 

Linear randomizing module 

HDAM sort exit routine 

Sample status code error routine 

Sample statistics print routine 

Sample data base load program 



• Job SAMP010 uses the DEDGEN procedure in INSVS.PKOCLIB. It must 
therefore be read in with an appropriate reader such as IMSRDE or 
PBIME. (See the previous section on installing IMS/VS.) The same 
is true for PSBGENs. 

• Jobs SAHP030 through SAHP03M use the standard ASMFC1 procedure in 
SYS1 .PFOCLIB. Also, when later compiling a COBOL or PL/I program we 
will use the standard supplied procedures of the respective language 
program product. 

• The linkage-edit phase cf jcb SAMP033 will give warning messages for 
unresolved references. This is a valid but expected situation, 
since this module will later be linked with the sample programs. 

PHASE 1 JOBS 

SAMPIOO: PSEGEN,for.Pbase^l_Data_Base_Load 

This job generates the PSE which will be used to load the Phase 1 FAETS 
data base. 

S AMPJOJ : PSEGENs_f or_.Phase_J x _COEOL 

This job generates the COBOL version of the PSBs which will be used in 
cur phase 1 environment. 

SAMP1 02 : P SBGENs_ f gr_Phase_1 X _PI^I 

This job generates the PI/I version of the PSBs which will be used in 
our phase 1 environment. 

2!2l§. : Tne load module names of the comparable COBOL and PL/I PSEs are 
the same. The same is true for the load module names of the comparable 
COBOL and PI/I sample application programs. Therefore you cannot 
intermix the COBOL and PL/I versions of the sample applications unless 
you change these load module names and their execution jobs. 
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SAMPJMO.: £BDGEN_fO£_Phase_J[ 

This job generates the PARTS DBD which will be used in our Phase 1 
environment. 

SAMP1U0 : Compile .and L^nk-edit Parts. Inventory .COBOL Program 

This job compiles and link-edits the parts inventory COBOL program, 
PE1CPINV (member DFS1CINV in IMSVS.PRIMESRC). Notice that in its 
link-edit, the DL/I language interface module (DFSLI000, alias CBLTDLI) 
is included. This is required for every COBOL application program- 
Also an ENTRY statement of DLITCBL is required. In addition the sample 
status code error routine (DFSOAER) and buffer pool statistics print 
routine (DFSOAST) are included, since they are used in the sample 
program. 

SAMP 141 : Co m£il e_and_Link -e di t _Purc hase_Or d ££_COBOL_Pr ogr am 

This job compiles and link-edits the Parts Purchase Order COBOL program, 
PE1CPP0R (member DFS1CP0R in IMSVS.PRIMESRC). 

SAMPJ.50:. Compile and Link-Edit Parts Inventory PL/I Program 

This job compiles and link-edits the Parts Inventory PL/I program 
PE1PPINV (member DFS1PINV in IMSVS.PRIMESRC). Notice that in its 
link-edit, the PL/I language interface module DFSLI000, alias PLITDLI) 
is included with entry point PLICALLA. This is required for every PL/I 
optimizer application program. In addition, the sample station code 
error routine (DFSOAER) and buffer pool statistics print routine 
(DFSOAST) are included, since they are used in the sample program. The 
link-edit step may result in a condition code 4. 

SAMP151 i Compile and Link-edit Purchase Order PL/I Program 

This job compiles and link-edits the Parts Purchase Order PL/I program, 
PE1PPP0R (member DFS1PP0R in IMSVS.PRIMESRC). 

SAMP 1.70; Load__theJPhase_J[_Data_Base 

This job does the space (re) allocation for the phase 1 PARTS data base 
and its initial load. 

The sort E61 exit routine (DFSOASRT) is used to sort the input data file 
in physical HDAM sequence. This sort is a performance option and is not 
necessary for the load process itself. 

The IMS/VS supplied DLIBATCH procedure is used in this and the other 
DL/I batch jobs. The application program to be executed is specified in 
the PARM field, together with other parameters. For a detailed 
discussion of these parameters refer to the DLIBATCH procedure 
discussion later in this chapter. 

si4MlZ! ' Execute _Parts Inventory. Program 

This job executes the Parts Inventory program (PE1CPINV) . 

This is a read-only job, so no log tape is used. 

U°.!t : If Y oa are using the PL/I version of the sample programs, the 
PL/I transient modules are presumed to be available in one of the 
libraries in the system linklist (LNKLST00) or the link pack area (this 
is recommended) . If not, you must add the PL/I transient library to the 
JOB/STEPLIB of the IMS/VS execution job. This can best be done by 
updating the appropriate IMS/VS procedure: DLIBATCH, IMSBATCH, and/or 
IMSMSG. 
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SAMPJ73: Exec ute_Purchase_Crder_ Program 

This jot executes the Purchase Order program (PE1CPPUR) . This program 
uses the DL/I batch checkpoint/restart facility. The sequential input 
(card) and output (print) files of this program are processed as GSAtf 
data bases. 

§^l-£l2ii : l2§2i?te _Fai ling_Purch as e_Or der_^r ogr am 

This job is the same as the previous, except that it issues message 
DFS3125A, after which it can be abnormally terminated (reply ABEND), 
continued (reply CONT) or cancelled. This will set an environment for 
jobs SAMP177 and SAHP178. If cancelled, the GSAM print file can be 
printed with a separate jet which consists of the LAST job step from 
SAMP17U. The corresponding restart job, SAMP178 will do this in its 
first step- 

SAMPJ.77: Sample_Eackout_Eun 

This job backs out the data base changes of the failing SAMP174 job. 
Eefore running this jcb you might wish to exercise log tape recovery, 
jobs SAMP190 and SAMP 191, and data base recovery, jobs SAMP181 and 
SAWP162. {See Chapter 6, "Data Ease Eecovery, " for more details.) In 
any case, the back cut job irust use a log tape (must be a tape) created 
by the failing job or the log tape recovery job (SAMP190 and SAMP 19 1). 
Never use a change accumulation tape for back out. 

Note: Message "EFS888, NO DATA BASE RECORDS FOUND FOE PSB=PEICPUR" may 
occur when backout is done from a (recovered) log tape after a 
(simulated) system failure during execution of sample job //SAME17U. 
This message occurs because the data base change records after the 
PPUB0010 checkpoint were net yet written to the log tape. This is a 
valid situation since these data base changes were also not yet written 
to the data base itself. 

SA M FJ78 : Be startup u£chase_Order_Progr am 

This job restarts the Purchase Order program from its latest successful 
checkpoint (PPUR0010) as specified in the PABM field of the EXEC 
statement. 

Observe in sample output (see Chapter 3 of the IMS^/VS Primer Sample 
£i§ting > s) that the checkpoint message output at restart (sample output 
job~7/SAMPl78, stepname LAST, ddname SYSUT2, page 006) is not exactly 
the same as the old output of the abnormal terminated job (sample output 
job //SAMP178, stepname OLDPRINT, ddname SYSUT2, page 006). The reason 
is that the program prints out the textlines: "CHECKPOINT SUCCESSFULLY 

TAKEN" and "PURCH. AMOUNT: " after the actual checkpoint. During 

restart the checkpoint itself is not repeated; the program gets control 
after the XRST call and reads in the next input transaction. 

S413IJJO • lJB§2©_Co]3 v._of _£he_Phase_J^Data_Base 

This job creates an image copy (back up) of the Phase 1 PARTS data base. 
In addition it executes a dummy batch and change accumulation jefc. This 
is to stress the need for a new change accumulation period after an 
image dump. If this was not done, the next change accumulation would 
include the last accumulated leg tape of the previous period. 

SAMIJJ3J2 Change_Accumulati£n_for_Phase J. 

This job performs the change accumulation of the Phase 1 log data sets. 
This job should be executed after each phase 1 job which creates a new 
log data set, that is, after SAMP173, SAMP17U, SAMP177, etc. 
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Note: In a typical user situation, the DFSULOG DD statement can 
concatenate multiple subsequent log tapes since the previous data base 
change accumulation execution. 

SAMP.1 82:. Onload Phase J. PARTS Data Base 

This job can be used to recover the Phase 1 PARTS data base using the 
image copy created by SAMP 180 and the change accumulation data set 
created by SAMP181. 

SAMPJ.85i Onload Phase 1. PARTS Data Base 

This job unloads the Phase 1 PARTS data base using the HD Reorganization 
Onload Otility. 

SAMPJ.86.: Reload Phase J, PARTS Data Base 

This job reloads the Phase 1 PARTS data base using the output created by 
SAMP185. 

SAMPJ.90 and SAMP1.91.: Log, tap_e Recovery. 

These jobs can be used to recover an unclosed log tape- This can be 
exercised by physically replacing the log tape with a scratch tape 
before replying CONT on the WTOR of SAMP17U. if no I/O errors occur 
before the end of the current log data set, the error block ID for job 
//SAMP191 is A0000 1, that is, the first (error) block after the current 
log data set. Note: If there is no data on the tape behind the current 
log data set, that is, a clean tape was used, then no error block will 
be listed. At termination (end of reel) the output log tape of 
//SAMP 190 will be properly closed by OS/VS. If so, job //SAMP 191 need 
not be executed, the output log tape of //SAMP190 can be used for 
back-out and change accumulation processing. 

PHASE 2 JOBS 

The Phase 2 jobs are related to the logical relationship function of 
DL/I. They should, therefore, only be exercised if you are planning to 
use this function. 

SAMP2001 Phase 2 PSBGENs 

This job generates the PSBs which will be used in the Phase 2 sample 
environment. 

SAMP2J.0:. Phase 2 DBDGENs 

This job generates the DBDs which will be used in the Phase 2 sample 
environment. 

SAMP243:, Com£ile and Link-edit Customer Order Program -- COBOL 

SAMP254:. Compile and Link^edit Customer Order Program-PL^I 
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SAMP270: Load Phase 2 Data Eases 

The prefix resolution step may issue a warning message for the existence 
of logical parents without logical children, quite a natural fact. As a 
result, the step will terminate with a condition code of ft, a valid 
situation. 

SAM£27l2 Execute Sample PL^I Program 

SAMF272:, Execute Customer Orders Program 

This jot executes the Customer Order Program, FE2C0FDR (member DFS2CCEE 
(COBOL) or DFS2PCFD (PI/I) in IMSVS. PFIMESRC) . During the execution of 
this job, the EB Monitor will be activated- See Chapter 9, 
"Optimization," for more details en the DB Monitor operation and output. 

SAM F 29 3.: Print DE Monitor Reports 

This job generates the DB Meritor reports from the output generated by 
job SAMP272. 

SAMP285^ Onload Phase 2 Data Bases 

The Phase 2 data bases PARIS and Customer Orders are unloaded as the 
first step in their reorganization. 

SAMP2J6-, Reload Phase 2 Data Bases 

Using the output of SAMP285, the Phase 2 data bases are reloaded as the 
second step in their reorganization. 

The prefix resolution step may issue a warning message for the existence 
of logical parents without logical children, quite a natural fact. As a 
result, the step will terminate with a condition code of ft, a valid 
situation- 

SAMP287: Onload Phase 2 Primary Index Data Ease 

This job can be used to unload the phase 2 primary INDEX data base of 
the HIDAM customer orders data base as the first step in its separate 
reorganization. 

SAMP2882 Feload_ Phase_2 Primary Index Data Base 

Dsing the output of the previous job, the primary Index data base of the 
HIDAM customer orders data base is reloaded as the second step of its 
separate reorganization. 

SAMP2 69: Phase 1 to Phase 2 Transition 

—_—____— _____ _ __ __. T .__ _ ———■——_——.—— 

This job can be used to create the Phase 2 data bases using the Phase 1 
data base as input. The result will be the same as after job SAMF270. 

The prefix resolution step may issue a warning message for the existence 
of logical parents without logical children, quite a natural fact. As a 
result, the step will terminate with a condition code of ft, a valid 
situation. 
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PHASE 3 JOBS 

SAMP3001 Phase. 3 PSBGENs 

SAMP3101 Phase 3 DBDGENs 

SAMP3UJ.2 Compile And Link^edit Purchase Order. Program -^ COBOL 

This job compiles and link-edits the Phase 3 COBOL Purchase Order 
Program. This is an upgrade of the Phase 1 version to include secondary 
index processing. 

SAMP^S.!! Compile and Link-edit Purchase Order Program-PL,/! 

This job compiles and link-edits the Phase 3 PL/I version of the 
Purchase Order Program. 

SAMP3701 £oad Phase 3 Data Bases 

The prefix resolution step may issue a warning message for the existence 
of logical parents without logical children, quite a natural fact. As a 
result, the step will terminate with a condition code of 4, a valid 
situation. 

S.AMP373J, lS§£u£§. Phase 3 Purchase Order. Program 

SAMP380i Image Coj>x £hase_3 Data Bases 

This job creates image copies of all the Phase 3 data bases. In 
addition, it creates an initial dummy change accumulation data set to 
emphasize the importance of image copy/change accumulation 
synchronization. 

SAMP38J.1 Phase 3 Change Accumulation 

SAM£382i Recover Phase 3 PARTS Data Base 

This job recovers the Phase 3 PARTS data base and its secondary index 
data base. It uses the PARTS image copy of SAMP380 and the change 
accumulation data set of SAMP38 1 or SAMP380. 

SAMP383 :, Recover Phase 3 CUSTOMER ORDER Data Base 

This job provides the same function as SAMP382 but for the CUSTOMER 
ORDERS data base and its primary index. 

SAMP38Ux Backgut Phase 3 Purchase Order Program 
This job is analogous to SAMP177 of Phase 1. 
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SAMP389i Phase 2 to Phase 3 Transition 

This job can be used to create the Phase 3 data bases from the Phase 2 
data bases. Notice that no user application programs are needed. The 
result will be the same as after SAMP370. 

The prefix resolution step may issue a warning message for the existence 
of logical parents without logical children, quite a natural fact. As a 
result, the step will terminate with a condition code of 4, a valid 
situation. 

PHASE U JOBS 

SAMPaOJ.: Phase_4_C0B0L_PSBGENs 

This job generates the COBOL version of the PSBs for the MPPs and BMPs 
which will be used in our Phase 4 environment. 

SAMP402: Phase _U_PL^I_PSBGENs 

This job generates the PL/I versions of the PSBs for the MPPs and BMPs 
which will be used in our Phase 4 environment. 

SAMP4JK): Phase_U_DBpGENs 

This job generates the DBDs which will be used in our Phase U 
environment. Note that the logical DBDs used in Phase 4 could have been 
introduced in Phase 3 (as suggested in Chapter 2) . 

SAMPU20: Phase_4_ACBGEN 

This job builds the ACBs from the DBDs and PSBs which will be used in 
our Phase 4 environment. This must be done before the CTL region can be 
started. 

SAMP425: Phase_4_For,mats 

This job generates the MFS control blocks used for the message and 
screen formats in our Phase 4 environment. When initially executed, 
message DFS1014I may occur and the jobstep terminates with a condition 
code of 4. This is a valid condition. 

S A M P44J[ : Com£ile_and_Link2edit _COBOL_C ust omer_Name_In juir y._MPP 

S AMP442 : Com£i le_and_Link2edit _COBOL_Cust omer .Qrder^Inguir £_MPP 

SAMP 443 : Com£i le _and_Link --edi t _COBQL_Cust omer _Order_Cr eat ion_MPP 

SAMP 444 : Com£i le _a nd_Link -edi t _C0 B OL_Cust omer _0r d er _Up_dat e^M PP 

§A M P 45J, : Comp_i l§_ana_Link-edi t _PL^I^ustomer_Naje_Inauirj£_MPP 

SAMP 4 52 : Com£i le_and_Link ^edi t _PL/I_Custoaer_Or der _Ing[uir y,_MPP 

S A MP453 : Compile and Link-edit PL/I Customer Order Creation _MPP 

SAMP 454 : Cont£i le^and^Link^edit _PL/I_Customer_Or der _U£dat e_MPP 

SAMP 47J, : l2L§£^i®-£ a .Ei§-Iliy.£S.l .£I_SUII 

This job executes the Phase 1 Parts Inventory program (PE1CPINV) as a 

BMP. 
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S A MP4 73 : Exec ute_|urcha§€_Order_ BMP 

This job executes the Phase 3 Purchase Order program (PE3CPPUR) as a 
BMP. The input provided tc the program will cause message DFS312 5A to be 
issued so that the online operating procedures may be tested. See the 
I!iS^vs_Messase_and_Codes_£§f§I for a detailed description of 

message DFS3125A. 

S A MP4 74 : Restart Purchase. Order BMP 

This job will restart the Purchase Order BMP if it has been cancelled by 
the operator, or has failed for seme other reason. Before execution you 
must verify that the checkpoint ID specified in the PARM field is the 
last one of the failing job. 

This job needs the log tape from the IMS/VS CTL region in its IMSLOGR dd 
statement, see Chapter 8, "Operations" and the IMS/VS Primer Master 
Terminal Operator* s Guide for more details. 

SAMP jf 81 : Pha se__ 4_Chan ge^Accu mu la t ion 

SAMP490_and_SAMPU9J: Lcg_TaC;e_Recoverv, 

These jobs can be used to recover an unclosed log tape in the online 
environment- Chapter 8, "Operation," describes how these jobs can be 
tested. 

SAMPJJ92: Log_Ta£e_Iermination 

This job uses the System Log Terminator utility to close an unclosed log 
tape in the online environment. Chapter 8, "Operation," describes how 
this job should be tested. 

SAMPU9U: £rint_pc_Mgnitgr_Eep.orts 

This job generates the DC Monitor reports from a DC Monitor data set 
produced during an online session. 

S A M P4 9 5 : Pri n t_Log_Tap_e_St at 1st ics 

This job prints statistical reports from the log tape produced by the 
online system. 

RECOMMENDED TEST SEQUENCE 

The recommended sequence for exercising the sample jobs is (numbers 
only) : 

1- Sample initialization and phase 0: 5, 6, 7, 9, 10, 31, 32, 33, 34. 

2. Phase 1 (COBOL): 100, 101, 110, 1U0, 141, 170, 180, 171, 173, 181, 
182, 170, 180, 174, 190, 191, 181, 177, 181, 178, 181, 182, 185, 
186. 

Phase 1 (PL/I): 100, 102, 110, 150, 151, 170, 180, 171, 173, 181, 
182, 170, 180, 174, 190, 191, 181, 177, 181, 178, 181, 182, 185, 
186. 

Note: For a successful exercise of the sample recovery jobs 174 and 
up, you must be familiar with the data base recovery utilities and 
procedures as presented in Chapter 6, "Data Base Recovery." 
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3. Phase 2 (COBOL): 200, 201, 210, 243, 270, 272, 293, 285, 286, 287, 
288, 289. 

Phase 2 (PL/I): 200, 202, 210, 254, 270, 272, 293, 285, 286, 287, 
288, 289. 

4. Phase 3 (COBOL): 300, 301, 310, 341, 370, 380, 373, 381, 382, 383, 
384, 389. 

Phase 3 (PL/I): 300, 302, 310, 351, 370, 380, 373, 381, 382, 383. 

5. Phase 4 (COBOL): 401, 410, 420, 425, 441, 442, 443, 444. 

Phase 4 (PL/I): 402, 410, 420, 425, 451, 452, 453, 454. After 
these jobs have been run, the online system may be started as 
described in the IMS/VS Primer Master Terminal Operators Guide. 
The online MPPs can then be exercised using the operating 
instructions in the IMS/VS Primer Remote Terminal Operator's Guide. 
Jobs 471, 473, and 474 should be run while the online system is up. 
Jobs 481, 490, 491, and 492 should be run when the MTO Guide and 
data base recovery procedures are tested, as described in Chapter 8, 
"Operations." Jobs 494 and 495 should use the tapes produced by the 
online system. 

If you want to skip the Phase 1, Phase 2 and Phase 3 sample batch jobs 
and proceed directly to the sample online system, just exercise the 
following jobs (numbers only) : 

• Sample initialization: 10, 30, 31, 32, 33, 34 

• Phase 1 jobs: 140 (COBOL) or 150 (PL/I). 

• Phase 3 jobs: 300, 310, 370, 301 and 341 (COBOL), or 302 and 351 
(PL/I) . 

• Than proceed with the Phase 4 jobs as described above. 

Note: The jobs are listed in job number sequence in Chapter 2 of the 
iHIZIsL ££iS§£ Samfile Listings manual. 

HDAM RANDOMIZING MODULES 

The HDAM access method requires a randomizing module for root segment 
retrieval and insertion. Each HDAM data base has only one randomizing 
module, but several data bases can share the same module. The module 
name and its parameters are specified in the DBD. 

The function of a randomizing module is to convert the root key of a 

data base record into an internal block and an anchor point address. 

This address is used by the HDAM access method for the storage and 
retrieval of data base records. 

The randomizing module is loaded by IMS/VS when the data base is opened. 
The normal OS/VS program load facilities are used; therefore, the module 
must reside in SYS1.LINKLIB or IMSVS. RESLIB if it is to be used by the 
online control region. If a randomizing module is used for more than 
one HDAM data base, that is, is a general randomizing routine, it should 
be reenterable (RENT) . 
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GENERAL RANDOMIZING MODULE 

DL/I supplies a general randomizing module which is suitable for most 
key ranges. This module, DFSHDC40, is used with all our sample HDAM 
data bases. 

You should write your own randomizing module only if you want to 
maintain rootlcey sequence and your key range is suitable for that. 

Note ; For more details on DFSHDC40 you should consult its source 
listing, which can be obtained from IMSVS. DBSOURCE. 

WRITING A RANDOMIZING MODULE 

When an application program issues a Get Unique, Get Next with 
Qualification, or Insert call which operates on a root segment of an 
HDAM data base, the user-supplied randomizing module is invoked. (See 
also Chapter 4, "Processing Data Bases," for more details on DL/I 
calls.) The root key value is supplied to the randomizing module for 
conversion to a relative block number and anchor point number within the 
data base. In addition to the field value parameter supplied by an 
application program, parameters from the DBD are available to the 
randomizing module in a CSECT named RDMVTAB. The address of this CSECT 
is passed to the module each time a conversion is requested. 

The following DSECT defines the format of this CSECT: 

DMBDACS DSECT 

NAME OF ADDR ALGORITHM LOAD MODULE 
0CL1 EXECUTABLE KEY LENGTH OF ROOT 
EP OF ADDR LOAD MODULE 
SIZE OF THIS CSECT 

NUMBER OF ROOT ANCHOR POINTS/BLOCK 
NUMBER OF HIGHEST BLOCK DIRECTLY ADDRSD 
MAX NUMBER OF BYTES BEFORE OFLOW TO 2NDARY 
CUR NUM OF BYTES INSERTED UNDER ROOT 
RESULT OF LAST ADDRESS CONVERSION 

^ndomJ.zing_Module_Ijit erf aces 

Upon entry to any randomizing module, registers must be saved. Upon 
return to DL/I, registers must be restored. A save area address is 
provided in Register 13 upon entry for the purpose of saving the 
registers. 

The following registers, on entry to a randomizing module, have the 
indicated meanings: 

£§2i§ter Ii~aHilLSL2£_£oriterit 

Data Management Block address (DMB) . 

1 DMBDACS CSECT address. 

7 Partition Specification Table address (PST) . 

The first 8 bytes can be used as working storage. 

9 Address of the first byte of the key field value 

supplied by an application program. 



DMBDANME 


DS 


c: 


DMBDAKL 


DS 


Oi 


DMBDAEP 


DS 


A 


DMBDASZE 


DS 


H 


DMBDARAP 


DS 


H 


DMBDABLK 


DS 


F 


DMBDABYM 


DS 


F 


DMBDABYC 


DS 


F 


DMBDACP 


DS 


F 
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Ji£Si§£is£ Weanin3_o£ - .Coi)t6nt 

13 Save area address, The first three words in the 

save area must not be changed. 

1U Return to IKS/VS address. 

15 Entry Pcint Address of randomizing module. 

The result of a randomizing module conversion must be in the form BEES 
where: 

EBE is a three-byte binary number of the block into which a root segment 
is to be inserted, cr frcm which it is to be retrieved. 

R is a one-byte binary number of the appropriate anchor point, within a 
relative block, within an CSAK data set of the data base. 

This result must be placed in the CSECT addressed by register 1 in the 
four-byte field named DMBDACP. If the result exceeds the content of the 
field DMBDABLK, the result is changed to the highest block and last 
anchor point of that blcck. 

A SIMPLE KEY-SEQUENTIAL RANDOMIZING MODULE 

This simple straightforward randomizing module does a linear conversion 
of the root key tc block, anchor point address. This routine (DFSOALIN 
in IKSVS.PRIMESRC) , can be used for numeric key ranges with an even 
distribution. 

DL^I_PATA_BASE_ED|FEBI1G_FACI1ITIES 

The DL/I buffering services are controlled by three pools of control 
blocks and buffers: the CSAK buffer pool, the DL/I buffer handler pool, 
and the VSAM buffer pool. This section describes the structure, 
content, and use of these pools by DL/I. 

The DL/I buffering services are the interface between the DL/I action 
modules (for example, Retrieve, Delete, Insert) and the data management 
access methods (VSAM and CSAK). Whenever an action module needs to 
inspect or change data in a data base, buffering services are called to 
perform whatever physical reading or writing is reguired. A separate 
pool of buffers is allocated for each type of data base: VSAM and OSAM. 
Data bases that use the VSAM access method share the use of buffers in 
the VSAM shared resource pool. Data bases that use the OSAM access 
method share the use of buffers in the OSAM buffer pool. 

The concept of the buffer pool allows blocks of data to remain in main 
storage as long as possible, in order to avoid secondary storage reads 
and writes. Data in the buffer pool can be accessed and updated without 
causing I/O as long as there is no need to reuse the buffer space the 
data occupies. A use chain determines the crder in which the buffers 
are used. Empty buffers are placed at the bottom of the use chain and 
are always available for reuse. As buffers are accessed they are placed 
at the top of the use chain. Hhen a retrieve reguest occurs, the buffer 
pool is searched using the use chain, to determine if the reguested data 
is already in main storage. If the data is not found, the least 
recently used buffer (bottom of the use chain) is selected, the old data 
is written out if it has been changed, and the reguested data is read 
into the selected buffer. 

If an I/O error occurs while attempting to write a buffer of data, the 
buffer is marked as a permanent write error buffer and retained in the 
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pool. No error indication is returned to the application program that 
encountered the error, but an I/O error message is written to the IMS/VS 
master terminal operator and/or OS/VS console operator, and an error log 
record is recorded on the IMS/VS log data set. 

Whenever an I/O error occurs, the DL/I Data Base Recovery Utility 
program should be used to re-create the data base that was damaged. 
# (See Chapter 6, "Data Base Recovery.") 

DL/I maintains statistics on buffer pool utilization and access method 
requests- These statistics can be used to determine the optimum buffer 
pool sizes for a job. The DL/I statistics call (STAT) can be used in an 
application program to obtain these statistics. See Chapter 4, "Data 
Base Processing," for a description of the STAT call and Chapter 9, 
"Optimization," for the interpretation of these statistics. 

LOG TAPE WRITE-AHEAD 

The log tape write-ahead option is provided to ensure that a data base 
log record for a data change is physically written to the log device 
before the changed data is physically written to the data base storage 
device. This ensures that any change made to a data base is physically 
recorded on the log tape before the data base is changed. This allows 
recovery, even in the case of loss of main storage contents due to power 
failure. 

The log tape write-ahead option is activated with the OPTIONS statement 
in the buffer pool initialization data set. See "Defining the IMS/VS 
Data Base Buffer Subpools" later in this chapter. In our subset, we 
will always select this option. 

THE DL/I BUFFER HANDLER POOL 

The buffer pool is the focal point for recording buffering services 
activity. The pool prefix (BFSP) contains pointers to the other elements 
of the pool, indicator flags, and some statistics. If VSAM data bases 
are used, a subpool statistics block (BFUS) exists for each VSAM buffer 
subpool defined. The subpool statistics block contains statistics on 
buffering services and VSAM request activity relevant to the associated 
subpool. These statistics can be requested with the STAT call. (See 
Chapter 4, "Data Base Processing.") 

THE VSAM BUFFER POOL 

The VSAM shared resource pool is used to buffer data for data bases that 
use VSAM. It is constructed by VSAM, as a shared resource pool, based 
on parameters provided by DL/I initialization. It contains buffers to 
be used for VSAM data sets (both index and data components) and the 
input/output control blocks necessary to perform VSAM requests. The 
buffers are combined in subpools. All buffers within a subpool are of 
equal length. 

If VSAM is used, the minimum number of subpools is 1 and the maximum is 
11. The minimum number of buffers in a subpool is 3, the maximum is 
255. Buffer sizes range from 512 to 32768 bytes and must be a power of 
2. For DL/I, VSAM control interval sizes may range from 512 to 30720 
bytes and must be a multiple of 512 (or a multiple 2048 if greater than 
8192). If no VSAM data bases are used, no VSAM subpools are required. 

During DL/I data base open, a data set is assigned a specific buffer 
subpool based on the control interval (CI) size. The CI size must be 
equal to or less than the buffer size for the subpool assigned. The 
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data and index components of a KSES may be assigned to different 
subpools if their CI sizes are different, and corresponding subpools 
exists. A single subpocl car. be defined with buffers large enough to 
contain the longest CI, or several subpools can be defined which more 
nearly fit the different sized CIs by the programs. 

THE OSAM EUIFIP POOL 

The OSAM buffer pool is used to buffer data for data bases that use the 
OSAM access method. The peel consists of one or more user defined 
subpools, comparable tc the VSAM buffer pool. Each subpool consists of 
fixed-length buffers. When a data set is opened, it is assigned a 
buffer subpool which contains buffers at least as large as the data set 
block size. If the data set block size is smaller than the buffer size, 
a portion of the tuffer space is net used. If data base data sets 
contain many different block sizes, many subpools must be defined to 
provide the best use of buffers. This can, in turn, restrict the number 
of buffers available tc any given data set. Another consideration is 
the deliberate separation of certain data bases to a specific subpool: 
a data base with high activity may tend tc monopolize a subpool. To 
avoid this, assign the data set a block size that causes it to be 
assigned a unique subpool. 

EEEINING THE IMS/VS DATA BASE BOFFEB SUBPCCIS 

The size and structure of the VSAM and OSAM buffer pools and the IMS/VS 
buffer handler pool are determined by control statements processed 
during IMS/VS initializaticr . 

In an IMS/VS batch system the control statements are in a data set with 
ddr.ame DFSVSAKF. 

In an online system, they are in a member of IMSVS-PF.OCLIB called 
DESVSMnn. (nn is a user-defined suffix which is also specified as a 
sub-parameter in the FARM field when executing the online system.) Job 
//SAMPI4 1 shows how this iremter can be created using the OS/VS utility 

IEBGENEB* 

Three types of control statements are allowed: the VSAM subpool 
definition statements, the OSAM subpool definition statements, and the 
OPTIONS statement. The subpool definition statement is used tc define 
the size and nuirber of buffers in a subpool. The OPTIONS statement 
allows the user to influence the performance facilities of the DL/I 
buffering services. 

YSAM_Subpool_ref initign__Statements 

/- " T 

/ I 

| size, number I 

! « 

I--, .-.-. j 



size 



A 3- to 5-digit number specifying the buffer size for this subpool, 
The permissible values are 512, 1024, 2C48, 4096, 8192, 12288, 
16364, 20480, 24576, 28672, and 32768. 



Installing IMS/VS 7.61 



number 

A 1- to 3-digit number (3 to 255) specifying the number of buffers 
in this subpool. If the number of buffers is less than the minimum 
required, it is increased to the minimum and a warning message is 
issued. 

Buffer size can start in position 1 or beyond and is separated from the 
number of buffers by a comma. Each statement defines one subpool. A 
blank must follow the number of buffers. The remaining portion of the 
statement is ignored. 

If two or more subpool definition statements specify the same buffer 
size, the numbers of buffers from the statements are summed, and a 
single subpool with the total number of buffers is built. 

£uideline§_for_Selectin£_Nu^ fej:s_£er_yj[AJ!_Sub£ool: Following 
is a basic guideline for the number of VSAM buffers per subpool in an 
entry environment. 

Number of buffers per VSAM subpool = 

3 

♦ (number of ESDSs served from this subpool) *2 

♦ number of KSDSs index components served from this subpool 

♦ number of KSDS data components served from this subpool 

Example : 

A batch program which uses all the data sets of the phase 3 sample data 
bases should specify: 

1024,6 
2048,9 

In the online environment the number of buffers should be calculated as 
shown above, but based on the MPP and BMP with the largest buffer pool 
requirement. The buffer pool requirements of the most demanding MPP 
should then be added to those of the most demanding BMP, and this total 
should be used as an initial estimate of the buffer pool requirements. 

Note; The number of subpool buffers can be easily adjusted during 
production. Chapter 9, "Optimization," contains guidelines for 
monitoring and adjusting this performance parameter. 

QSAM .Subpool ^Definition .Statements 

I0BF= (l,n,fl,f2) 

I0BF= is the required keyword for subpool definition. It must begin in 
the first position of the control statement. Only one subpool 
definition may appear on each control statement. 

1 

Specifies the length of the buffers in the subpool. This parameter 
is required. If it is invalid, the entire entry will be ignored. 
The parameter must be in the range 512-32000 bytes. The value that 
is specified is rounded up to the nearest power of 2, up to UK. 
Thereafter, the value is rounded to a multiple of 2K. 
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f1 



f2 



n 

Specifies the number of buffers in the subpool. This parameter is 
optional. If specified, it must be in the range 4-255- The default 
value is 4. If this parameter is invalid, the remainder of the 
entry will be ignored, and defaults will apply for all remaining 
parameters. 

Specifies the buffer long-term-page-fixing option. This parameter 
is optional. If Y is specified, all buffers and buffer prefixes 
associated with this subpccl will be long-term-page-fixed at 
initialization of the subpool. If N is specified, no buffers 
associated with this subpccl will be long-term-page-fixed at 
initialization of the subpool. The default is N. If this parameter 
is invalid, the remainder of the entry will be ignored, and defaults 
will apply for all remaining parameters. Y is recommended. 

Specifies the buffer prefix long-term-page-fixing option. This 
parameter is optional. If Y is specified, all buffer prefixes 
associated with this subpool and the subpool header will be 
long-term-page-fixed at initialization cf the subpool. If K is 
specified, the subpool header and all buffer prefixes associated 
with this subpool will net be long-term-page-fixed at initialization 
of the subpool. The default is N. Y. is recommended. 

Guideline s_f gr_ Select ing_JNumber - of_ Juf f ers_per_OSAM Subpool: Following 
is a basic guideline for the number of VSftM buffers per subpool in an 
entry environment. 

Number cf buffers per OSAW subpool = 



♦ (number of OSAM data sets served frcm this subpool) *2 

In the online environment the number of buffers shculd be calculated as 
shewn above, but based on the MEF and EME with the largest buffer pool 
requirement. The buffer peel requirements cf the most demanding MEF 
should then be added to those of the most demanding BMP, and this total 
should be used as an initial estimate of the buffer pool requirements. 

Note: The OSAM buffer pool definition statements need not necessarily 
be specified for a DL/I batch job. If not specified, a minimum of 4 
buffers per subpcol will be allocated in our subset. 

Example: Job //SA3F174 shews the use of the OSAM subpool definition 
statements together with the LTWA option. 

QEUQNS.Statement 

OPTIONS, LTWA=YES,VSAMFIX= (EFB,ICB) ,BHTSACE=0 

CPTICNS, INSEET = SKPJ SEQ 

The word CPTICNS, starting in position 1 identifies the OPTIONS 
statement. The parameters can be specified in any sequence and must be 
separated by commas. ft blank must follow the last parameter. The 
remaining portion of the statement is ignored. An OPTIONS statement 
cannot be continued on a subsequent statement, but several CPTICNS 
statements may be provided. If an OPTIONS parameter appears more than 
once, its setting is determined by the last cccurrence. 



Installing IMS/VS 7.63 



LTWA=YES 

Activates the log tapa write-ahead function of DL/I. This should 
always be specified to concur with our subset recovery procedures. 

VSAMFIX=(BFR,IOB) 

This is a performance option. It normally should be selected. 

BHTRACE=0 

Suppresses the DL/I buffer handler trace, which is not part of our 
subset. 

INSERT=SKP| SEQ 

Specifies the insert mode that the buffer handler uses when 
inserting new KSDS logical records in a data base (SHISAM and 
INDEX) . If a program inserts many new root segments in sequence by 
key, than specifying INSERT=SEQ causes the buffer handler to use 
VSAM sequential mode POTs. VSAM leaves free space (if specified in 
the DEFINE) in CIs created for the new records that are inserted. 
(VSAM refers to this as "mass insert") . Specifying INSEFT=SKP, or 
omitting the parameter, causes the buffer handler to use VSAM skip 
sequential mode PUTs. SEQ should ba selected for initial load and 
mass insert jobs. It is automatically enforced in the 
reorganization reload utilities- INSERT=SEQ will be ignored in the 
online control region. 

IMS^VS SECURITY MAINTENANCE UTILITY 

The IMS/VS system security utility is used to define your terminal and 
password security. This utility must be initially executed after each 
Stage 2 of IMS/VS system definition, before the CTL region is started. 
It can be re-executed whenever you want to change your terminal/password 
security. The new security will become effective at the next start 
(cold or warm) of the CTL region. 

EXECUTING THE SECURITY MAINTENANCE UTILITY 

During IMS/VS system definition, a procedure named SECURITY is placed in 
IMSVS. PROCLIB. With this procedure you can create your own transaction 
and terminal security matrices which are stored in the IMSVS. MATRIX data 
set. Jobs //SAMPIUU and //SAMPI45 in IMSVS. PRIMEJOB show how to use the 
SECURITY procedure. 

Note: Even if you don f t intend to use the IMS/VS security facility, you 
must run job //SAMPIUU (BTAM) or //SAMPI45 (VTAM) . If you fail to, you 
will be unable to start the CTL region because there would not be at 
least one password entry as required by our IMS/VS system definition. 

Security,_Status_Re£ort 

Each execution of the security maintenance utility produces a printed 
analysis of the IMS/VS system for which security is being maintained. 
If errors are encountered in processing the program's input control 
statements, no security block update functions are performed. 

Instead, diagnostic error messages are produced for the entire input 
stream. 
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Note: The security status report should be properly maintained as it is 
vital to the security cf the system, 

IOIS_0F_SYSTIM_S|C0EITI 

The following types of security are distinguished in our subset: 

• Command security: Certain commands are restricted to the master 
terminal. 

• Terminal security: Certain transactions are restricted to selected 
logical terminals. 

• Transaction security: Certain transactions will be accepted only 
when the terminal operator also enters a defined password. 

COMMAND SECURITY 

IMS/VS includes during system definition a default command security 
which we will use. With this default command security, the following 
commands are restricted to the master terminal: /ASSIGN, /CHANGE, 
/CHECKPOINT, /CLSEST, /COMPT, /DBDUMP, /DBRECOVERY, /DELETE, /DEQUEUE, 
/DISPLAY, /ERESTART, /IDLE, /MONITOR, /MSASSIGN, /MSVERIFY, /NRESTAET, 
/OPNDST, /PSTOP, /PURGE, /RSTART, /SMCOPY, /START, /STOP, and /TRACE. 
As we will only use a subset of IMS/VS commands, it is recommended to 
protect the non-subset commands with a special password. This will 
prohibit the accidental use cf those commands by an operator. The first 
part of the input of job //SAMPIUU and //SAMPI4 5 shows how to do this. 
The special password is defined by the statement: 

) ( PASSWORD NONPRIME 

The commands to be protected are specified via the immediately following 
COMMAND ... statements. 

No t es : 

1. The commands are abbreviated to their first 3 characters, a standard 
IMS/VS feature. 

2. Obviously, you should change the password (NONPRIME) to your own. 

TRANSACTION AND TERMINAL SECURITY 

A set of input control statements is reguired for each transaction code 
is to be assigned password and/or terminal security. 

2SMJACT Statement: One TRANSACT statement is reguired for each 
transaction code that requires security. Its format is: 



/ ■ 

/ 

) ( TRANSACT trancode 



i 



t- ------ ------- ---------- — .--..-.--...--.-..-----......-....-...j 
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Legend: 

The ) ( oust be coded in columns 1 and 2 and be followed by a blank. The 
TRANSACT operand must be followed by a blank and the transaction code 
(trancode) • 

PASSWOBD Statement: This statement should be included only if you want 
the preceding transaction code to be protected by a password. Its 
format is: 

/ i 

/ * 

| PASSWORD password < 

I I 

«.--..-.-- J 



L ege nd: 

The PASSWORD operand must be preceded and followed by at least one 
blank. The specified password must be 1 to 8 alphanumeric characters. 

TERMINAL Statement: One TERMINAL statement is required for each logical 
terminal authorized to enter this transaction. If no TERMINAL statement 
follows a TRANSACT statement, then that transaction code is accepted 
from an.y, terminal. The format of the TERMINAL statement is: 



/ 



1 

! 

TERMINAL lterm-name • 



Legend: 

The TERMINAL operand must be preceded and followed by at least one 
blank. The specified lterm-name must be defined during IMS/VS system 
definition via a NAME statement. 

IMS^VS_CATALOGED_PROCEDURES 

Several procedures are placed in the IMSVS.PROCLIB by Stage 2 system 
definition. 

The following are applicable to our subset environment and are used in 
our sample jobs: 

• ACBGEN builds online control blocks from your DBDs and PSBs 

• DBDGEN generates data base definition control blocks {DBDs). 
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DLIBATCH executes a batch DL/I program. 

IMSBATCH executes a batch message processing program (Phase u 
only) . 

IMS executes the online control program (Phase 4 only) 

IMSMSG executes the online message processing programs (Phase 4 
only) . 

IMSEDR is the reader procedure for using IMSVS. PROCLIB 

MFSRVC builds an index directory used by the online MPS pool 
manager. 

MFSUTL generates MFS control blocks (Phase 4 only) 

PSBGEN generates program specification blocks (PSBs) . 

SECURITY generates the security blocks used by the online control 
program (Phase 4 only). 

In the following overview of these procedures, we will discuss the 
execution parameters only of interest to our subset. For those 
parameters not discussed, you should use their default values. 



ACBGEN PROCEDURE 



// PROC 

//G EXEC 

/VSYSPRINT DD 
//STEPLIB DD 
//DFSRESLB DD 
//IMS DD 

// DD 

//IMSACB DD 
//SYSUT3 DD 
//SYSUT4 DD 
/VCOMPCTL DD 



SOUT=A,COMP=,RGN=160K 

PGM=DFSRRC00 , PARM= ' UPB , 8C0MP • ,REGION=*RGN 

SYS0UT=4S0UT 

DSU=IMSVS.RESLIB,DISP=SHR 

DSH=IMSVS.RESLIB,DISP=SHR 

DSU=IMSVS . PSBLIB ,DISP=SHR 

DSN=IMSVS.D£OLIB,DISP=SHR 

0SN=IMSVS.ACBLIB,DISP=010 

UNIT=SYSDA,SPACE=<60,<100,100>) 

UNIT=SYSDA ,SPACE = < 256 ,(100,100)) ,DCB=KEYLEN=8 

DSN=IHSVS.PROCLIB(DFSACBCP>,DISP=SHR 



0000001 
0000002 
0000003 
0000004 
0000005 
OOC0006 
0000007 
0000008 
0000009 
0000010 
0000011 



EXEC Statement Parameters for ACBGEN 

SOUT= 

specifies the SYSOUT class. 
COMP= 

specifies the library compression option. Specify POSTCOMP for 
in-place compression after new members are added for best 
performance. 



RGN- 



Specifies the region size for MVS users. 
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DBDGEN PROCEDURE 



DO 



DO 



// PROC 

//C EXEC 

//SYSLIB DD 

//SYSGO DD 

// 

// 

//SYSPRINT DD 

// 

//SYSUT1 

// 

//SYSUT2 

// 

//SYSUT3 

// 

//L 

//STEPLIB DD 

//SYSLIN DD 

//SY5PRINT DD 

// 

//SYSLMOD DD 

//SYSUT1 DD 

// 



DD 



EXEC 



MBR=TEMPNAME,SOUT=A 0000001 

PGM=IFOX00,REGION=256K,PARM='OBJ,NODECK' 0000002 

DSN=IMSVS.MACLIB,DISP=SHR 0000003 

UNIT=SYSDA,OISP=( .PASS), 000000** 

SPACE=(80,(100,100),RLSE), 0000005 

DCB=(BLKSIZE=400,RECFM=FB,LRECL=80) 0000006 

SYSOUT=&SOUT,0CB=BLKSIZE=1089, 0000007 

SPACE= (121, (300, 300 ),RLSE,, ROUND) 0000008 

UNIT=SYSDA,DISP=< .DELETE), 0000009 

SPACE=(1700,(100,50)) 0000010 

UHIT=SYSDA,DISP=< .DELETE), 0000011 

SPACE=<1700,<100,50) ) 0000012 

UHIT=(SYSDA,SEP=(SYSLIB,SYSUT1,SYSUT2)), 0000013 

SPACE=(1700,(100,50)) 0000014 
PGM=DFSILK'KO ,PARM= 'XREF , LIST ' ,COND=( , LT.C ) ,REGION=120K 0000015 

DSU=IMSVS.RESLIB,DISP=SHR 0000016 

DSN=*.C.SYSGO,DISP=( OLD, DELETE) 0000017 

SYSCUT=&SOUT,DCB=BLKSIZE=1089, 0000018 

SPACE=(121,(90,90),RLSE) 0000019 

DSN=IHSVS.DBDLIB(&M3R),DISP=SHR 0000020 

UHIT=(SYSDA,SEP=(SYSLMOO, SYSLIN) ), 0000021 

SPACE = (102<+,(100,10),RLSE),DISP=( .DELETE) 0000022 



See the section entitled "Execution of DBDGEN (JCL) " in Chapter 2, "Data 
Base Design" for details on using this procedure. 



DLIBATCH PROCEDURE 



// PROC MBR=TENPNAHE,SOUT=A,PSB=,BUF=7, 0000001 

// SPIE=0,TEST=0,EXCPVR=0,RST=0,LOGT=2400, 0000002 

// FRL0=,SRCH=0,CKPTID=,MCN=N,LOGA=0, 0000003 

// FMTO=T,IM3I0= 0000004 

//G EXEC PGM=DFS3RC00,RESION=192K, 0000005 

// PARM=(DLI,*KBR,£PSB,&BUF, 0000006 

// SSPIE&TEST&EXCPVR&RST.&FRLD, 0000007 

// SSRCH.XCKPTID.JMCH.&LOGA.iFHTO, 0000008 

// 4IN3ID) 0000009 

//STEPLIB DD DSN=IMSVS.RESLIB,DISP=SHR 0000010 

// DD DSM=IMSVS.PGMLIB,DISP=SHR 0000011 

//DFSRESLB DD DSN=II1SVS.RESLIB,DISP=SHR C000012 

//IMS DD DSM=IMSVS.PSBLIB,OISP=SKR 0000013 

// DD DSN=IMSVS.DCDLIB,DISP=SHR 000001<+ 

//PR0CLIB DD DSN=IMSVS.PPOCLIB,DISP=SHR 0000015 
//IEFR0ER DD DSN=IMSLCG,DISP=( .KEEP ) ,VOL=< , , ,99) ,UNIT=( &LOGT, .OEFER ) , 0000016 

// DCB=(RECFM=VB,BLKSIZE = 1920,LRECL=1916,B'JFNO=2) 0000017 

//SYSUOUMP DD SY5CUT=4SOUT,DCB=(RECFM=FBA,LRECL=121,BLKSIZE=605), 0000018 

// SPACE=<605, (500, 500), RLSE, .ROUND) 0000019 

//IMSUDUMP DD SYSCUT=&S0UT,DCB=(RECFM=FBA,LRECL=121,BLKSIZE=605)^ 0000020 

// SPACE=<605, (500, 500), RLSE,, ROUND) 0000021 

//IMSMON DD DUMMY 0000022 

Notes: 

1. The BLKSIZE and LRECL values shown in the IEFRDEF dd statement are 
the default values. If the DCB parameters are changed, log 
initialization calculates the smallest value necessary for logical 
record length. If the JCL logical record length value is larger 
than the calculated value, the JCL value is used; otherwise, log 
initialization uses the calculated value for logical record length 
and adds 4 for the block size. 

2. This statement describes the recording device to be used by the DB 
monitor. It is required only if MON=Y is specified in the PROC 
statement, and then only if a device other than the IMS/VS system 
log is to be used for monitor data. When a separate log device is 
used for DB monitor data, a //IMSMON DD statement must be included 
that specifies a sufficient BLKSIZE and LRECL (2048 and 2044 are 
suggested) . 

3. You must add the DD statements for all the data bases the job step 
uses. 
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U. A DFSVSAMP DD statement roust be added for the LTWA option and the 
OSAM and/or VSAM subpccl specifications. 

EXEC Statement Parameters for DLIBATCH 
MBF = 

specifies the application program name. 
SOOT= 

specifies the class assigned to SYSOTJT ZL statements. 

PSB = 

is an optional parameter specifying a PSB name when the PSB name and 
application program name are different. 



BDF = 



specifies the data bas€ buffer size- If not present, a default size 
of 7K will be used. Buffer size is specified in 1K multiples. 
Values may range from 1 through 999. Using IOBF= cards in the 
DFSVSAMP data set will override this parameter. 



SPIE= 



specifies the SPIE option: 0= allow user SPIE, if any, to remain in 
effect while processing the application program call. This option 
is recommended. 

1= negate the user's SPIE while processing the application program 
call. Negated SPIEs are reinstated before control is returned to 
the application program. 



TEST* 



specifies whether J1) cr not (C) the addresses in the user's call 
list should be checked for validity. Zero (0) is the recommended 
value- 

EXCPVK= 

specifies whether EXCP (C) or EXCPVR (1) is to be used for data sets 
processed by OSAM (0S/VS1 only). One is the recommended value if 
the program accesses OSAM data bases, otherwise zero should be 
specified. 

FST~ 

must be zero 10) in cur subset. 

PFLE= 

should be omitted in our subset. 

SBCH = 

is the module search indicator for directed load: 
0= standard search. 

1= search JPA and 1PA before JOBLIE/STEPLIB (MVS only). 
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CKPTID= 



specifies the checkpoint at which the program is to be restarted; 
specified as a 1-to 8-character extended checkpoint ID- If no 
checkpoint exists, this parameter should be omitted. 



MON= 



specifies whether (?) or not (N) the DB monitor is to be active for 
this execution. See Chapter 9, "Optimization," for a description of 
the DB Monitor and its use. 



LOGA = 



specifies the use of BSAM (0) or OSAM (1) for the logging facility. 
1 is the recommended value. is the default. 



LOGT = 



specifies the tape device type where the log data set will be 
mounted. The default is device type 2100. 



IMSID= 



specifies a four character identifier that is a valid subsystem 
identifier to the operating system being used. This identifier will 
be used instead of the identifier specified at system generation of 
the IMS/VS system being executed. Multiple batch jobs with the same 
identifier are allowed to run concurrently. So you normally don't 
need to specify this parameter except when you want to separate a 
test and production version. 
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IMS PBOCEDURE 



// PROC RGN=600K,SOUT=A,DPTY= , (14,15)', 

// DUMPDS=DUMMY ,DV= ,DU= , LOGT=2400 , 

// CTL=CT,RGSUF=L,RES=,FRE=,QBUF=,DYBN=,PST=, 

// SAV= , EXVR= ,PRF= ,SRCH= , FBP= , PSB= ,DMB= , 

// DBB= , TPDP= , WKAP= , PSBW= ,CWAP= ,DBUP= , 

// MFS= ,SUF= , FIX= , PRLD= , VSPEC=00 ,SOD= , 

// IOB=,VAUT=,LOGA=0,FMTO=T, 

// AUTO=N,RDBN=2,TRN=N, 

// SGN=N,RCF=N,IMSID=IMSA,ISIS=0, 

// LOGD=0 

//IEFPR0C EXEC PGM=DFSRRC00,REGION=£RGN,DPRTY=8DPTY, 

// PARM=(8CTL8RGSUF, 

// 8RES , 8FRE , 8GBUF , 8DYBN , 8PST , 8SAV , 

// SEXVR,8PRF,8SRCH,8FBP,SPSB,8DMB,8DBB, 

// 8TPDP , 8WKAP , 8PSEW , 8CWAP , lUB'AP , 8MFS , 

// 8SUF , 8FIX » 8FR LD , 8VSPEC , SSOD , 8IOB , 

// 8VAUT,,,,,, 

// 8 LOSA , 8FMTO , 8AUTO , 8RDBN , 8TRN , 8SGN , 

// &RCF,8IMSID,8ISIS,,8LOGD) 

//* 

//* 

//* THE MEANING AND MAXIMUM SIZE OF EACH PARAMETER 

//* IS AS FOLLOWS: 

//* 

//******** CONTROL REGION SPECIFICATIONS ******** 



//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 
//* 



RGSUF 

RES 

FRE 

QEUF 

DYBN 

PST 

SAV 

EXVR 

FRF 

SRCH 



SOD 
IOB 
VAUT 
LOSA 

FMTO 



RDBN 
TRN 



SGN 



RCF 



IMSID 
ISIS 



LOGD 



X 

X 

XXX 

XXX 

XXX 

XX 

XXX 

X 

X 

X 



X 

XXX 

X 



X 



EXEC PARM DEFAULT BLOCK SUFFIX 

BLOCK RESIDENT (N = NO, Y = YES) 

NUM3ER OF FORMAT REQUEST ELEMENTS 

NUMBER OF MESSAGE QUEUE BUFFERS 

NUMBER OF DYNAMIC LOG BFFRS FOR PI 

NUMBER OF PST ' S 

NUMBER OF DYNAMIC SAVE AREA SETS 

PAGEFIX DYN LOG AND QM3R BUFFER POOLS <1=YES, 0=NO) 

PREFETCH OPTION (Y = YES, N = NO) 

MODULE SEARCH INDICATOR FOR DIRECTEO LOAD 

= STANDARD SEARCH 

1 = SEARCH JPA AND LPA BEFORE PDS 
1 CHARACTER SYSOUT CLASS 

NUMBER OF OSAM I/O REQUESTS 

VTAM AUTH PATH OPTION (1=YES, 0=NO) 

= BSAM FOR LOGGING (DEFAULT) 

1 = OSAM FOR LOGGING 

T = FORMATTED DUMP WITH 

STORAGE IMAGE DELETIONS 
P = FULL FORMATTED DUMP 
N = NO FORMATTED DUMP 
Y = AUTOMATIC RESTART DESIRED 
N = NO AUTOMATIC RESTAPT 



XXXXX NUMBER OF RESTART DATA SET BUFFERS 
X TRANSACTION AUTHORIZATION CHECKING 

F = FORCED, Y = YES, N = NO 
X SIGNON AUTHORIZATION CHECKING 

F = FORCED, Y = YES, N = NO 
X RACF USED FOR TRANS. AND SIGNON 

Y = YES, N = NO 
XXXX IMS/VS SUBSYSTEM IDENTIFIER 
X = NO RESOURCE ACCESS SECURITY 

1 = RACF RESOURCE ACCESS SECURITY 

2 = USER RESOURCE ACCESS SECURITY 

X = NO LOG VOLUME DEQUEUE (DEFAULT) 
1 = DEQUEUE LOG VOLS AT EOV (MVS) 



0000001 
0000002 
0000003 
0000004 
0000005 
0000006 
0000007 
0000008 
0000009 
0000010 
0000011 
0000012 
0000013 
0000014 
0000015 
0000316 
0000017 
0000016 
0000019 
0000020 
0000021 
0000022 
0000023 
0000024 
0000025 
CC00C26 
0000027 
0000023 
0000029 
0000030 
0000031 
0000032 
0000033 
0000034 
0000035 
0000036 
0000037 
000003S 
000C039 
0000040 
0000041 
0000042 
0000043 
0000044 
0000045 
0000046 
00O0C47 
000004S 
0000049 
0000050 
0000051 
0000052 
0000053 
0000054 
0000055 
0000056 
0000057 
0000058 
0000059 
0000060 
0000061 
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//* 


FBP 


XXX 


//* 


PSB 


XXX 


//* 


OMB. 


XXX 


//* 


DEB 


XXX 


//* 


TFDP 


XXX 


//* 


UXAP 


XXX 


//* 


PS5W 


XXX 


//* 


CWAP 


XXX 


//* 


DBWP 


XXX 


//* 


MFS 


XXX 


//* 






//***#**** tf 


IEM8EI 


//* 






//* 


SUF 


X 


//* 


FIX 


XX 


//* 


PRLD 


XX 


//* 


VSPEC 


XX 



//* 

//#**###** STORAGE POOL SIZES IN IK BLOCKS ****** 

//* 

MESSAGE BUFFER POOL 

PSB POOL 

DM3 FOOL 

DATA BASE BUFFER POOL 

TP DEVICE I/O POOL 

WORKING STORAGE BUFFER POOL 

PSB WORK POOL 

SPA POOL 

DATABASE WORK POOL 

MAXIMUM MFSTEST SPACE 



LAST CHARACTER OF CTL PROGRAM LOAD MODULE MEMBER 
2 CHARACTER FIX PROCEDURE MODULE SUFFIX 
2 CHARACTER FROCLIB MEC3ER SUFFIX FOR PRELOAD 
2 CHARACTER BUFFER POOL SPEC MODULE SUFFIX 

//KM********************************************* 
//* 

//OFSRESLB DD DSN=IMSVS.RESLIB,DISP=SHR 

//FRCCLIB DD DSN=IMSVS.PROCLIB,DISP=SHR 

//IEFROER DD DSN=IMSVS . IMSLOG,DISP=( .KEEP ) , 

// VOL=( ,,,99),UNIT=(&LCGT,,0EFER), 

// OCB=( RECFM=VB ,BLKSIZE=3992 , LRECL=3968,BUFN0=2 ) 

//IMSL03R DD DSN=IMSVS.IMSLOG, 

// DISP=(MOD,KEEP),UMIT=AFF=IEFRDER 

//IMSMON DD DSN=IM5V5. IMSMON, DISP=( .KEEP), 

// VOL=( ,,, 99), UNIT=(SLCGT,, DEFER, SEP=IEFRDER) 

//Q3LKS DD DSN=IM3VS.G3LKS,DISP=0LD 

//SKMSG DD DSN=IMSVS.SHMSG,DISP=OLD 

DSN=IMSVS.LGMSG,DISP=OLD 

DSM=IMSVS . ACBLIB , DISP=SHR 

DSN=IMSVS.FORMAJ,DISP=OLD 

SYSOUT=«SOUT, 
// DCB=( LPECL=125,RECFM=FBA,BLKSIZE=3129), 
// SPACE=< 6050, 300, ,, ROUND) 
//IMSRDS DD DSN=IhSVS.RDS,DISP=OLD 
//DUMP DD SDUMFDS, 
// OISP=OLD,LABEL=( ,NL)80V40U 
//IMSUDUNP DO SYSOUT=£SOUT, 
// DCB=(LRECL=125,RECFM=FBA,BLKSIZE=3129), 
// SPACE=<6050,300,, .ROUND) 

DD DSH=IMSVS. MATRIX, DISP=SKR 

DD SYSOUT=£SOUT 

DD 0SN=IMSVS.DBLLOG,DISP=SNR 



//LGMSG DD 
//IMSACB DO 
//IMSDILIB DD 
//SYSUDUMP DD 



//MATRIX 

//FRINTDD 

//IMSDBL 

//* 

//* USER MUST SUPPLY THE DD STATEMENTS 

//* FOR THE ON-LINE DATA BASES TO BE 

//* INSERTED HERE FRIOR TO ATTEMPTING 

//* AN ON-LINE SYSTEM EXECUTION USING 

//* THIS PROCEDURE. 



0000062 
0000063 
0000064 
0000065 
0000066 
0000067 
0000063 
0000069 
0000070 
0000071 
0000072 
0000073 
0000074 
0000075 
0000076 
0000077 
NAME0000078 
0000079 
0000080 
0000081 
0000082 
0000083 
0000084 
0000085 
0000086 
0000087 
0000088 
C0C0089 
0000090 
0000091 
0000092 
0000093 
0000C94 
0000095 
0000096 
0000097 
000009S 
0000C99 
0000100 
0000101 
0000102 
0000103 
0000104 
0000105 
0000106 
0000107 
0000108 
0000109 
0000110 
0000111 
0000112 
0000113 
0000114 
0000115 



Notes: 

1. The program name specified on the EXEC statement is DFSRRCOO for 
OS/VS1 and DFSMVRCO for MVS. 

2. The BLKSIZE and LRECL values shown in the IEFRDER dd statement are 
the default values. If the DCB parameters are changed, log 
initialization calculates the smallest value necessary for logical 
record length. If the JCL logical record length value is larger 
than the calculated value, the JCL value is used; otherwise log 
initialization uses the calculated value for logical record length 
and adds 4 for the block size. 

3. The DD statement called IMSMON describes the recording device to be 
used by the DC Monitor and is required only if you wish to invoice 
the monitor during an online session. 

4. The above listed IMS procedure is produced for the VTAM only system. 
The procedure for the BTAM only system is the same, but will contain 
DD statements for the communication lines. 
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5. In our subset, you must add the DD statements for the data base data 
sets to be used by the control region to this procedure- See job 
//SAMPI4C in IMSVS.PRIMEJOB. 

EXEC Statement Subset Parameters for IMS Procedure 

EGN= 

specifies the size of the region in which the control program 
is to run, and has meaning only in an MVS system. 



SODT= 



DPTY= 



CTL = 



VSPEC= 



FIX= 



VAUT= 



LOGA = 



specifies the class to be assigned to SYSODT DD statements. 



specifies the OS/VS dispatching priority at which the IMS/VS 
control region should operate. See the OS/VS JCL documentation 
for details of DPTY. The IMS/VS control region must not be 
executed at priority zero, or be scheduled into an OS/VS 1 
partition whose priority falls within JES1 DDG, or into an MVS 
region whose priority falls within a JES2 APG. A general rule 
to follcw is that the IMS control region dispatching priority 
must always be higher than the dispatching priority of an 
IMS/VS dependent region. 



specifies whether IMS/VS should operate as a system task. 
CTI=CT1 indicates that it should run as a system task; CTI=CTX 
indicates that it should run as a problem program. CTL=CTL is 
recommended. 



specifies the two-digit suffix of the DFSVSMnn member of 
IMSVS.PP0C1IB that contains the VSAM and OSAM buffer pool 
specifications to be used. 



specifies the two-digit suffix of the DFSFIXnn member of 
IMSVS.PEOCLIB which controls the fixing in real storage of 
selected parts of the CTL region. 



specifies whether (1) cr not (0) IMS/VS is to use the VTAM 
authorized path facility. The recommended option is 1. 



specifies which legging facility, ESAM or OSAM, IMS/VS is to 
use. Specify 1 for OSAM, the recommended option. 

The other symbolic parameters need not be specified because the default 
values calculated during systeo definition should be sufficient for our 
entry environment. 



LOGT= 



specifies the tape device type. The default is device type 
2400. 
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LOGD= 

specifies whether (1) or not (0) IMS/VS output log volumes are 
to be dequeued at EOV. This parameter is valid for MVS only. 
The recommended value is 1 especially if you consider restarts 
of BMP, which use the XRST call. 

IMSBATCH PROCEDURE 

// PROC MBR=TEMPNAME,S0UT=A,OPT=N,SPIE=0,TEST=t>, 0000001 

// PSB=,PRLD=,STIMER=,CKPTID=,IN=,OUT=,DIRCA=000, 0000002 

// PARDLI=,CPUTIME=,NBA=,OBA=,IMSID=,AGN= 0000003 

//Q EXEC PGM=DFSRRC00,REGION=128K, 0000004 

// PARtt=(BMP,&MBR,&PSB,4IN,&0UT, 0000005 

// &OPTSSPIE*TEST&0IRCA,SFRL0,&STIMER,aCKPTID, 0000006 

// &PARDLI,*CPUTIME,4NBA,40BA,&IMSID,&AGN) 0C0C007 

//STEPLIB DD DSN=IMSVS.RESLIB,DISP=SHR 0000C08 

// DD DSN=IMSVS.PGHLIB,DISP=SHR 000C009 

//FROCLIB DD DSN=IHSVS. PPOCLIB,DISP=SHR 00000X0 

//SYSUDUMP DD SYS0UT=&S0UT,DC3=( LRECL=121 ,RECFM=VBA,BLKSIZE=3129 ) , 0000011 

// SPACE=(125, (2500, 100), RLSE,, ROUND) 0000012 

Note; You must add a DD statement for the log tape containing the 
checkpoint data when you are restarting a BMP which uses the XRST call. 
This DD statement has the DDname IMSLOGR. 

EXEC Statement Parameters for IMSBATCH 
MBR= 

specifies the application program name. 
SOUT= 

specifies the class assigned to SYSOOT DD statements. 

PSB= 

is an optional parameter specifying a PSB name when the PSB name and 
application program name are different. The PSB name must be 
defined as PGMTYPE=BATCH with an APPLCTN macro in your IMS/VS system 
definition. 

SPIE = 



specifies the SPIE option: 0= allow user SPIE, if any, to remain in 
effect while processing the application program call. This option 
is recommended. 

1= negate the user's SPIE while processing the application program 
call. Negated SPIEs are reinstated before returning to the 
application program. 



TEST= 



specifies whether (1) or not (0) the addresses in the user's call 
list should be checked for validity. Zero (0) is the recommended 
value. 
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PRLD= 

should b€ omitted in our subset. 

CKFTID= 

specifies the checkpoint at which the program is to be restarted, 
specified as a 1-to 8-character extended checkpoint ID. If this is 
not a restart run, this parameter should be omitted. 



CPT= 



specifies the action to be taken if the batch message region starts 
and there is no ccntrcl program active. 

N -- ask operator for decision. This is the default. 
H -- wait for a control region- 

C — cancel the batch message region automatically. 
N is the recommended value. 



IS = 



should be omitted in cur subset. 
COT= 

should be omitted in our subset. 
DIBCA= 

should be omitted in cur subset.. 

IMSMSG PBOCEDOPE 

//MESSAGE JOB 1,IMS,MSGLEVEL=1 ,PRTr=U,CLASS=A,MSGCLASS=A,REGI0N=128K 0000001 

//REGION EXEC PGM=DFSRRC00 ,REGION=126K , 0000002 

// TIhE=1440,DPRTY=<12,0), 0000003 

// PARM='KSG,0010000000CO' 0000004 

//STEPLIB DD DSN=IMSVS.RESLIB,DISP=SHR 0000005 

// DD DSN=*MSVS.PGMLIB,DISP=SKR 0000006 

//FROCLIB DO DSN=IMSVS.FROCLIB,DISF=SHR OC00007 

//SYSUDUMP DD SYS0UT=A,0CB=< LRECL=121 ,BLKSIZE=3129 ,RECFM=VBA ) , 000000S 

// SPACE=(125, (2500, 100), RLSE,, ROUND) 0000009 

This procedure must be copied to IMSVS.JCES. See job //SAMPI4 2 in 
IMSVS.PEIMEJOE. 
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IMSRDR PROCEDURE 



// 

//IEFPROC 

// 

//* 

//* 

//* 

//* 

//* 

//* 

//* 

//* 

//* 

//» 

//* 

//* 

//* 

//* 

//* 

//IEFRDER 

//IEFPDSI 

// 



PROC MBR=IMSMSG 

EXEC PGM=IEFVMA, READER FIRST LOAD 

PARM='00100300005210E00011AXX' DEFAULT OPTIONS 
BPPTTTTSSCCCRLAAAAEFHXX PARM FIELD 
B PROGRAMMER NAME AND ACCOUNT NUM3ER NOT NEEDED 
PP PRICRITY=01 
TTTTSS JOB STEP INTERVALS 30 MINUTES 
CCC JOB STEP DEFAULT REGI0N=52K 
R DISPLAY AND EXECUTE C0MMANDS=1 
L BYPASS LABEL=0 
AAAA COMMAND AUTHORITY FOR MCS=EOOO 

- ALL COMMANDS MUST BE AUTHORIZED 
E JCL MESSAGE LEVEL DEFAULTS -ALL MESSAGES 
F ALLOC/TERM MESSAGE LEVEL 0EFAULT=1 -ALL MESSAGES 
H DEFAULT MSGCLASS=A 

XX PARTITION, RDR WILL HAVE DISPATCHING 
PRIORITY 1 LOWER THAN PARTITION 
SPECIFIED. XX=SYSTEM TASK PRIORITY 
DO OSN=IMSVS. JOBSt &MBR ) ,DISP=SHR ,DCB=BUFN0=1 
DD DSN=IMSVS.PROCLIB,DISP=SHR 
DD DSN=SYS1.PR0CLIB,0ISP=SHR 



0000001 
0000002 
0000003 
0000004 
0000005 
0000006 
0000007 
0000008 
0000009 
0000010 
0000011 
0000012 
0000013 
0000014 
0000015 
0000016 
0000017 
0000018 
0000019 
0000020 
0000021 



This procedure must be copied to SYS 1. PROCLIB. 
IMSVS.PRIMEJOB. 



See job //SAHPI2U in 



PSBGEN PROCEDURE 



oo 



DD 



// PROC 

//C EXEC 

//SYSLIB DD 

//SYSGO DD 

// 

// 

//SYSPRINT DD 

// 

//SYSUT1 

// 

//SYSUT2 

// 

//SYSUT3 

// 

//L 

//STEPLIB DD 

//SYSLIN DD 

//SYSPRINT DD 

// 

//SYSLMOD DD 

//SYSUT1 DD 

// 



DO 



EXEC 



MBR=TEMPNAME,SOUT=A 0000001 

PSMsIFOXOO.REGIOh^OOK.PARMs'OBJ.NODECK' 0000002 

DSN=IM5VS.MACLIB,DISP=SHR 0000003 

UNIT=SYSDA,DISP=< ,PASS), 0000004 

SPACE=<80,(100,100),RLSE), 0000005 

DCB=(BLKSIZE=400,RECFM=FB,LRECL=80) 0000006 

SYSOUT=8SrUT,DCB=BLKSIZE=1089, 0000007 

SPACE = ( 121,1 300,300),RLSE, .ROUND) 0000008 

UNIT=SYSOA,DISP=< , DELETE), 0000009 

SPACE=< 1700,(100,50)) 0000010 

UNIT=SySDA,DISP=( .DELETE), 0000011 

SPACE=(1700,(100,50)) 0000012 

UNIT=(SYS0A,SEP=(SYSLIB,SYSUT1,SYSUT2)), 0000013 

SPACE=(1700,(100,50)) 0000014 
PGM=DFSILNKO , PARM= ' XREF , LIST ' ,COND=( , LT.C ) ,REGION=120K 0000015 

DSN=IMSVS.RESLIB,DISP=SHR 0000016 

DSH=*.C.SYSGO,DISP=< OLD, DELETE) 0000017 

SYSOUT=*SOUT,DCB=BLKSIZE=1089, 0000018 

SFACE=(121,(90,90),RLSE) 0000019 

DSH=INSVS.PSBLIBUMBR),DISP=SHR 0000020 

UNIT=(SYSDA,SEP=( SYSLMOD, SYSLIN)), 0000021 

SPACE = (1024,(100,10),RLSE),DISP=( .DELETE) 0000022 
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SECURITY PROCEDURE 



// PROC 


//S EXEC 


//STEPLIB 


DD 


//SYSPRINT 


DD 


//SYSPUNCH 


DO 


// 




// 




//SYSLIN 


DD 


// 




// 




//SYSUT1 


DD 


// 




//SYSUT2 


DD 


// 




//SYSIN 


DD 


//C EXEC 


//SYSPRINT 


DD 


//SYSGO 


DD 


// 




// 




//SYSUT1 


DD 


//SYSUT2 


DD 


//SYSUT3 


DD 


// 




//SYSIN 


DD 


//L EXEC 


//STEPLIB 


DD 


//SYSPRINT 


DD 


//SYSLMOD 


DD 


//INFUT 


DD 


//SYSUT1 


DD 


//SYSLIN 


DD 



OPTN=UPDATE,IMS=' ,0' ,SOUT=A 0000001 

PGM=DFSISMP0,PARM='&OPTN.&IMS. ' 0000002 

DSN=IMSVS.RESLIB,DISP=SHR 0000003 

SYSOUT=&SOUT,DCB=(RECFM=VBA,BLKSIZE=129,LRECL=125) 0000004 

UNIT=SYSDA,SPACE=(80,(800,400),,,RCUND), 0000005 

DCB=( RECFM=FB, LRECL=80 ,BLKSIZE=400 ) , 0000006 

DISP=(NEW,PASS) 0000007 

UNIT=SYSDA,SPACE=(TRK,<1,1)), 0000008 

DCB=(PECFh=F,BLKSIZE=80), 0000009 

DISP=(NEU,PASS) 0000010 

UNIT=SYSDA,DCB=(BLKSIZE=500,RECFM=FB), 0000011 

SPACE=( 100, (400, 400),,, ROUND) 0000012 

UNIT=(SYSDA,SEP=SYSUT1),DCB=*.S.SYSUT1, 0000013 

SPACE=( 100, (400, 400),,, ROUND) 0000014 

DSN=NO. SYSIN. DD. ASTERISK 0000015 
PGM=IFOX00,PARM= , OBJ,NODECK' ,COND=( 12 , LT,S ) ,REGION=128K 0000016 

SYSCUT=SSOUT,DCB=BLKSIZE=1089 0000017 

UNIT=(SYSOA,SEP=SYSPRINT),DISP=( ,PASS), 0000018 

SFACE=( 60, (400, 400),,, ROUND), 0000019 

DCB=*.S. SYSPUNCH 0000020 

UNIT=SYSDA,SPACE = (CYL,(5,D) 0000021 

UNIT=SYSDA,SPACE=(CYL,(5,1) ) 0000022 

UNIT=(SYSDA,SEP=(SYSUT1,SYSUT2) ), 000002 3 

SPACE = (CYL,(5,D) 0000024 

DSN=*.S. SYSPUNCH, DISP=(OLD, DELETE) 0000025 
PGM=DFSILNK0,PARM=' LIST,NE,OL' ,REGION=110K ,COND=( 4 , LT,S ) 0000026 

DSN=IMSVS. MATRIX, DISP=SHR 0000027 

SYSOUT=&SOUT,DCB=(RECFM=FBA,LRECL=121,BLKSIZE=605) 0000028 

DSN=IMSVS. MATRIX, DISP=SKR 0000029 

DSN^.C.SrSGO.DISP::' OLD, DELETE) 00C0030 

UNIT=(SYSDA,SEP=INFUT),SPACE = (CYL,(5,D) 00000 31 

DSN=*. S. SYSLIN, DISP=( OLD, DELETE) 0000032 



MFSRVC PROCEDURE 



// PROC DEVCHAR=0 

//MFSRVC EXEC PGM=DFSUTSAO ,REGION=250K, PARM= 'DEVCHAR=*DEVCHAR ' 

//* 

//« PRINT FILES 

//* 

//SYSPRINT DD SYSOUT=A 

//* DCB=(RECFM=VBA,LRECL=137) 

//SYSSNAP DD SYSOUT=A 

//* DCB=(RECFM=VBA,LRECL=125,BLKSIZE=1632) 

//SYSUDUMP DD SYSOUT=A 

//* 

//* REFERAL LIBRARY 

//* 

//REFIN 

//* 

//* 

//* 

//FORMAT 

//* 

//* 

//* 

//* 

//* 

//* 

//* 

//* 

//# 



DD DSN=IMSVS. REFERAL, DISP=OLD 

ON-LINE FORMAT LIBRARY 

DD DSN=IMSVS. FORMAT, OISP=OLD 



//SYSIN DD * MUST BE SUPPLIED BY 
USER WITH INPUT CONTROL CARD STREAM 



ALL DISP=OLD SPECIFICATIONS OF THIS 
PROCEDURE ARE REQUIRED 



0000001 
0000002 
0000003 
0000004 
0000005 
0000006 
0000007 
0000008 
0000009 
0000010 
0000011 
0000012 
0000013 
0000014 
0000015 
000CC16 
0C0C017 
0000018 
0000019 
0000020 
0000021 
0000022 
0000023 
0000024 
0000025 
0000026 
0000027 
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MFSUTL PROCEDURE 



// 
// 
// 
// 
// 
//si 

// PARM='« 

// LINECNT 

//*SYSLIB 

//SYSIN 

//REFIN 

//REFOUT 

//REFRD 

//SYSTEXT 

// 

//SYSUT3 

//SYSUT* 

//DUMMY 

//UTPRINT 

//SYSPRINT 

//SYSUOUMP 

//SEQ5LKS 

// 

//S2 

// 

// 

//SEQBLKS 

//UTPRINT 

//SYSUDUMP 

//FORMAT 

//DUMMY 

//SYSPRINT 

//SYSUT3 

//SYSUT* 

//* 

//* 



PROC RGN=360K,SOUT=A,SNCDE=IMSVS, 

SCR=NOLIB,MBR=NOMBR,PXREF=NOXREF, 

PCOMP=NOCOMP , PSUBS=N0SU3S , PDI AG=NODI AG , 

COMPR=NOCCMFPESS,COMPR2=C0MFRESS, 

LN=55 , SN=8 , DEVCHAR=0 
EXEC PGM=DFSUPAA0,REGION=8RGN, 
PXREF , iPCOMP , &PSUBS , &FD I AG , &COMPR , 

«LN,STOFRC=iSN,DEVCHAR=&DEVCHAR' 
- USER OPTION 
OD DSN=&SNOOE. . 8SOR. UKBR ) ,DISP=SHR 
DD 0SN=IMSVS.REFERAL,DISP=OLD 
DD DSN=IMSVS.REFERAL,DISP=OLD 
DD DSN=IhSVS.REFERAL,DISP=OLD 
DD DSN=&&TXTPASS,UNIT=SYSOA, 

SPACE = (CYL,(1,D)»DCB=BLKSI2E=800 
DD UNIT=SYSDA,SPACE = <CYl,(l,m 
DD UNIT=SYSDA,SPACE = (CYL,(1,D) 
DD DSN=IMSVS.PROCLIB(REFCPY),DISP=SHR 
DD SYSOUT=SSOUT 

DD SYSOUT=&S0UT,DCB=(RECFM=FBA,LPECL=133,BLKSIZE=1330) 
DD SYSOUT=«SOUT 
DD DSN=SaBLKS,DISP=(NEW,PASS), 

UNIT=SYSDA,SPACE = (CYL,(1,D) 
EXEC FGM=DFSUNUB0,REGION=*RGN, 

PARM= ' &CCMPR2 ,DEVCHAR = ?-DEVCHAR ' , 

C0UD=(8,LT,S1) 
DD DSN=&£BLKS,DISP=(OLD, DELETE) 

DD SYSOUT=&SOUT,DCB=<RECFM=FBA,LRECL=133,BLKSIZE=1330) 
DD SYSOUT=&SOUT 
DD DSN=IMSVS. FORMAT, DISP=OLD 
DD DSN=IMSVS.PPOCLIB(FMTCPY),DISP=SHR 
DD SYSOUT=SSOUT 

DD UNIT=SYSDA,SPACE=(CYL,(1,1>) 
DD UHIT=SYSDA,SPACE=(CYL,<1,1)) 



0OOOOO1 
0000002 
0000003 
000000* 
0000005 
0000006 
0000007 
0000008 
0000009 
0000010 
0000011 
0000012 
0000013 
000001* 
0000015 
0000016 
0000017 
0000018 
0000019 
0000020 
0000021 
0000022 
0000023 
000002* 
0000025 
O0OC026 
0000027 
0000028 
0000029 
0000030 
0000031 
0000032 
0000033 
000003* 
0000026 
0000027 



GHOWING_FROM_DB_Tg_DB/DC 

Although this is not an IMS/VS requirement we recommend that DB-only 
users wishing to upgrade to a DB/DC system re-do the entire IMS/VS 
installation, following the steps outlined in the section "INSTALLING 
IMS/VS DB/DC." The only step that should be omitted is the allocation 
and construction of the application libraries DBDLIB, PSBLIB and PGMLIB. 
The sample job stream in IMSVS. PRIMEJOB is constructed in such a way 
that the scratching and allocating of these libraries is done in a 
separate job (SAMPI15) which can be omitted when doing the installation, 

INSTALLING IMS/VS UNDER QS/VS2iMVS 

The installation of IMS/VS under OS/VS2-MVS is much the same as 
described for OS/VS1 in the first part of this chapter. 

THE INSTALLATION JOBS 

The jobs necessary to install IMS/VS under OS/VS2 MVS are, in general, 
the same as for OS/VS1. The differences are listed below and/or 
included in IMSVS. PRIMEJ03 with a prefix of SMVS. 

The following exceptions/additions apply: 

1. The IMSCTRL macro of the Stage 1 definition should specify: 

SYSTEM= (VS/2, BATCH, 3.7) for a DB installation [//SAMPI21) 

or 

SYSTEM^ (VS/2, ALL, 3.7) for a DB/DC installation {//SAMPI22, 

//5AMPI23) 
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2. Both VTAM and the IMS/VS online control region run as authorized 
subsystems under MVS. You must include the libraries from which 
IMS/VS, VSAM and NCP/VS are loaded and executed in the appropriate 
authorization tables. Note that you should not concatenate 
IMSVS. RESLIB with unauthorized libraries such as PGMLIB on the 
STEPLIE or JOELIB DD statement of the IMS online control region 
procedure, as this will cause the job step to become unauthorized. 
The DL/I, MPP, and BMP regions do not require IMS/VS to run as an 
authorized subsystem. 

3. If you choose to concatenate IMSVS. RESLIE to SYS1.LINKLIB in 
LNKLSTOO, the node IMSVS may not be used as a CVCL pointer. If you 
wish to use it as a CVCI pointer you should consider renaming the 
FESLIE. In our example the equivalent of job //SAMFI01 in the 
OS/VS1 installation, job //SMVSI01 builds an IMSVS CVOL pointer 
using Access Method Services. This job requires selectable unit 8 
(SOS) to be installed in your 0S/VS2 (MVS) system. If you don't have 
SU8 installed, you cannot build an index structure for node IMSVS in 
the CVOL on IMSPEM. Instead you should catalog the IMSVS data sets 
in a VSAM catalog. 

U. The resource clean-up module DFSMFCLO must be link-edited into 
SYS1.LPALIB, and the IEAVTEML CSECT of module IGC0001C in 
SYS1.LPALIB must be updated. Jobs //SMVSI27 and //SMVSI33 show an 
example of the JCI to do this. The actual CSECT offset is in 
general 00. For mere details see "Clean-up Routines" in the "CS/VS2 
System Programming library: Supervisor." After this job has been 
executed the system must be re-IPLed with the CLPA option. 

5. The abend formatting module DFSAFMDO must be link-edited into 
SYS1.LPAIIB under the name IGC0905A. See job //SMVSI27. 

6. If your MVS system uses JES2, you must add IMSVS. PFOCLIB to the 
concatenation fer PFOC00 in the JES2 reader procedure. A job for 
this update is not provided in our sample jobs because of the 
critical nature of the JES2 procedure. A JCL error in this 
procedure leaves MVS without any readers, printers, or initiators. 
Another system must be used to correct the error. Therefore, it is 
recommended that this update be performed by the MVS system 
programmer. 

Certain considerations are involved when concatenating the 
IMSVS. PRCCLIB to the EBCC00 DD statement in the JES2 procedure: 

the volume with the named data set must be available at every 
IPL. 

the data set referenced first must have the largest block size 
or a • DCE=BLKSIZE s = • cverride parameter on the ED statement. 
Some procedures generated by IMS/VS system definition reference 
IMSVS. PECCLIE members as input to the linkage editor, which 
might have a blocksize restriction in your installation. 

the named PFOCLIB data set must be cataloged on the master 
catalog or must be referenced by the 'UNIT*' and »VOL=SEF=' 
keyword parameters in its DD statement. If cataloged in the 
master catalog, you cannot use the node name as a CVOL pointer. 

the most elegant solution is to copy the IMS/VS procedures to 
SYS 1. PFOCLIB, or tc copy the IMSVS. PFOCLIB under a different 
name to one of the system resident volumes and catalog it in 
the master catalog. 
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7. The VTAM storage pool specification on //SAMPI5U should be adapted 
to your installation and VTAM level. Notice that the recommended 
IOBUF and PPBUF buffersize of 336 must be the same as the UNITSZ= 
value on the HOST macro of the NCP (job //SAMPI61). 

8. The program name on the execution statement of the VTAM start 
procedure should be changed from ISTINA01 to ISTINM01 (job 
//SAMPI55) . 

9. The program name on the execution statement of the GTF procedure 
should be changed from HHLGTF to AHLGTF (job //SAMPI56) . 

10. The UNITSZ value on the HOST macro in job //SAMPI61 must be equal to 
the buffer size of the IOBUF and PPBUF storage pools in job 
//SAMPI54. See also note 7 above. 

11. Whether or not the IMS/VS CTL region is executed as a system task or 
a problem task is dependent upon its starting as a system task via 
the OS/VS console or its starting as a problem task via JES. 

THE SAMPLE JOBS 

The sample jobs are the same as for OS/VS1. If you don't have SU8 
installed, you must build the generation data groups in the VSAM user 
catalog (job //SAMP009) . In addition, all data set names of the 
generation data groups (log and image copy data sets) in the sample jobs 
should use the node IMSPRIME instead of IMSVS. This is due to the 
difference in the VSAM catalog mechanism for generation data groups for 
OS/VS 1 and OS/VS2 without SU8. 

Ijxecutina the Samp_le Jobs with QS/VS2 MVS 

Executing of the OS/VS 2 MVS sample jobs can be best done by submitting 
them from IMSVS. PRIMEJOB. The following job can be used to read those 
jobs from their job library and submit them to an internal reader: 

A, 'IMS/VS-PRIMER' 

JOB=TEMPNAME 

PGM=IEBGENER 

SYSOUT=A 

DUMMY 

DSN=IMSVS. PRIMEJOB (&J0B) ,DISP=SHR 

SYSOUT= (A f INTRDR) , DCB = BLKSIZE=80 

SUBMIT, JOB=jobname 

MAINTENANCE CONSIDERATIONS 

To provide for the continuing exapansion of hardware and software 
functions, IBM provides at regular intervals new releases of IMS/VS. 
Before using a new release and/or function, you might want to test them 
in your environment, but isolated from your existing (production) 
system. 

It is recommended that you maintain separate production and test version 
of the following system libraries: LOAD, GENLIB, DBSOUPCE, OBJDSET, 
PRCCLIB, MACLIB, MATRIX, JOBS, and RESLIB. From an application 
development point of view, you might want to maintain separate versions 
of DBDLIB, PSBLIB, FORMAT, REFERAL, AND PGMLIB. 



//SUBMIT 


JOB 


//SUBMIT 


PROC 


//STEP1 


EXEC 


//SYSPRINT 


DD 


//SYSIN 


DD 


//SYSUT1 


DD 


//SYSUT2 


DD 


// 


PEND 


//SUBMIT 


EXEC 
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System Modification Program 1SMP]l 

The OS/VS System Modification Program (SMP) is available to IMS/VS users 
as an option. SMP is a facility that allows you to apply program 
temporary fixes (PTFs) or user modifications either selectively or as a 
group to VS1 or VS2 or the distribution libraries (DLIBs) associated 
with them. See the OS^VS System Modification Program (SMP) System 
E£2a£§.lS§£iS Guide for a detailed description of SMP. A sample SMP job 
stream is provided to demonstrate what must be done to maintain your 
IMS/VS libraries using SMP. 

This sample SMP job stream is on file 4 of your Data Base System tape- 
It may require minor changes depending on your system configuration. A 
detailed description of this job stream and its use is included in the 
P£22£ikSl 2i£§£^2£2 which accompanies the IMS/VS distribution tape. 

H®2£®§>§i°.£ l£§iiQ.2 2i New IMS/VS Releases 

Hhen you are installing a new IMS/VS release, it is recommended to 
perform some kind of regression test before you use this new IMS/VS 
release as you production system. The IMS/VS Primer function sample 
jobs, although not explicitly designed for this purpose, can be used as 
an initial test vehicle. When your installation grows, you might 
complement this with a subset of your production jobs and procedures. 

Quite often, initial test cases used during development are also very 
useful for regression testing. Therefore they should be maintained even 
after the application goes into production- 
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CHAPTER 8. CJEFftSIONS 



This chapter discusses the factcrs involved in operating IMS/VS online. 
It shculd be read in conjunction with the IMS/VS Primer operator 1 s 
guides: 

• I]?S^VS_Primer_Master_Terminal_^ 

• IMS^VS_PriBer_B€Bote_leijinal_Oj:er^t 

These guides are examples cf a Master Terminal Operator's guide (MTC 
guide) and a Demote Terminal Operator's guide (BTO guide) in either a 
VTAM or ETRM environment. The MTO Guide also has a detailed discussion 
of the IMS/VS (and VTAM) commands used in our subset. 

«HAT^S_Ng£DED - 10_C|ElAT|.CKlINi - 2MS^?S 

An online system puts a greater demand on an operations staff than a 
pure batch system. We have categorized the extra work into four groups, 
called functions, which arc described below. Because each 
organization's policies and structure will determine how the functions 
will be implemented, we have limited ourselves to a discussion cf the 
characteristics of each. However, it is important that these functions 
be recognized and the responsibilities assigned to specific individuals 
in the organization. 

Two of these functions, the Master Terminal Operator and the User 
liaiscn Group, are also discussed in greater detail later in this 
chapter. 

TH1 MASTER TERMINAL OPERATOR FUNCTION 

This function has the responsibility for the operation of the IKS/VS 
online system, including: 

• Starting and stopping the system and its resources. 

• Displaying system information. 

• Carrying out emergency recovery procedures as outlined by EE and/or 
DC Administration. 

THE NEISCRK CCM1BCI FOKCTICK 

This function has the respcnsibilty for the physical maintenance of the 
terminals and associated equipment in the network including: 

• Interfacing with the suppliers of the communication lines and any 
other equipment in the netwcrk- 

• Co-ordinating the installation of new terminals and associated 
equipment. 
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THE APPLICATION SUPERVISCF FUNCTION 

This function has the responsibility fcr maintenance of all programs and 
transactions in specific applications- Eersons performing this function 
should have a detailed knowledge of applications, and ideally should be 
involved in the original design and analysis phases for them. This 
responsibility includes: 

•• Handling all gueries relating to that application which are routed 
to them by the Raster Terminal Operator or the User Liaison group 
(see belov) . 

• Handling problems such as an application program abend, or a reguest 
by a remote terminal operator for clarification of a user procedure. 

IHE USER IIAISCN FCBCTICK 

This function provides the first point of contact for all remote 
terminal operators nho experience problems with, or who have gueries 
about, the online system- As such, they: 

• Provide assistance in the analysis cf such problems, whether they 
are related to hardware, software, cr a specific application. 

« Route problems or gueries which they cannot resolve to the 

appropriate function: Network Control, Master Terminal Operator, cr 
Application Supervisor. 

Note: We recommend that the Master Terminal Operator never be contacted 
directly by remote terminal operators, but that all gueries be routed 
through the liaison function. 

5HE^MAS1ER_TE|BINAI_CPI|ATCE_JKTC1 

As stated earlier, the person assigned to this function is responsible 
for the operation cf the cnline IMS/VS system. We recommend that, 
during any one shift, one specific operator be designated as the MTO, 
and that he te the cnly cne whc uses the master terminal during that 
period. However you should ensure that more than one person in your 
installation is trained as an MTO to provide backup. 

It is important that the MTO be familiar with all the operating 
procedures he may be called upon to use. It is also important that 
formal reporting procedures are established, so that he can document any 
problems he encounters. Examples of forms to be used for this purpcse 
are shown in the sanple MTO Guide. 

The interface between the MIO and the other functions in the 
organization must be clearly defined. He should be given a list shewing 
whom he is to contact in DC Administration, Network Control, User 
Liaison, and the Application Supervisor group. 

THE MAS1EE TERMINAL CEEB*TCE»S GUIDE 

This sample guide can he used easily by an operator. It is also a 
learning tool. It includes only those procedures used by an KTC, and 
dees net cover procedures for error situations to be handled fcy a 
support group such as DC Administration. The sample guide is designed 
in such a way that it can be easily maintained and extended with 
additional procedures as the network is increased and new applications 
are added. This document is not meant to replace the IMS/VS_Messages 
§S^-Q2^§§_Sil§£fSS§_l!§i313lI' b u-t i* i s t0 ^ e used in conjunction with it. 
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MODIFICATIONS TO THE SAMPLE MTO GUIEE 

If you wish to use the sample guide in your installation you will need 
to make some modifications tc tailcr it to your own needs. 

IllSc£ional_Titles 

The functions described above are referenced in the guide with the 
names: DC Administration, Application Supervisor, Network Control, and 
User Liaison. If you do net use these titles in your organization you 
should replace them with the appropriate titles. You should alsc file 
with the guide a list cf the names and telephone numbers of the people 
responsible for each function. 

OS/VSl_Installations 

The sample guide is designed for use in an CS/VS 1 installation. It 
assumes that ycu are running the IMS/VS control region in partition F1. 
If this is not correct for your installation, you should modify Chart 
E-2, "Initializing the IMS/VS Ccntrol Begion. " 

M V. ^Installations 

If you use MVS in your installation, you will have to modify the chart 
described above ic the OS/VS1 section, and also Chart E-7 (OS/VS 
abends). In addition, you have to use bypass label processing (BiE) in 
the IMSLCGF EC statement of the BME restart JCL (//SAMP474) if the BMP 
restart is across a CIL region restart. This is because 0S/VS2 MVS 
restores its volume serial enqueue on the input log tape in the CTL 
region. This can also be avoided by stopping and restarting the CTI 
regicn immediately after the emergency restart, and before the BMP 
rest art- 
Subs et_Limit at ions 

The MTC guide is designed upon the IMS/VS Primer Function subset as 
defined in Chapter 1, "Introduction. " As a result, certain IMS/VS 
functions are not included in our MIO guide. This is particularly true 
for the enhanced disk restart. The rationale behind this is that we 
feel that you should first gain experience with leg tape restart before 
using disk restart. However, once you are familiar with log tape 
restart, we encourage you tc switch to disk restart and adapt your MTC 
guide tc that respect. 

I°^J£_§IJd._T.ables 

The sample MTO Guide includes in Chapter 4 tables which describe the 
network in cur sample system, and details of the sample programs, 
transactions and data bases. These tables should be changed to reflect 
the configuration of your installation. 

Eestart_and - Fecgyer2_JCI 

In the sample MIC guide, the operator is told to run certain batch 
recovery/restart jobs. Figure 6-1 shows a table of these jobs, where 
they are referenced, and the corresponding sample jobs in 
IMSVS.PFIMEJOE. 
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JCB DESCRIPTION 



EMF Restart 

System log lerminator 

Log Tape Recovery — Part 1 

Leg Tape Recovery — Part 2 

Change Accumulation 

Data Ease Recovery 

Batch Backout 



| CHAET 


SAMPLE 1 


} A-1,E-5 


| SAMP47I* | 


J H-2 


SAMP492 | 


| H-3 


| SAMPU90 | 


| H-3 


SAMP491 | 


1 1-1 


| SAMP481 | 


1 1-1 


| SAMP382 | 


I 1-1 


| SAMP384 | 



Figure 8-1. Jcfcs requiring JCL modification 



These charts should be updated to reflect the actual job names used in 
ycur installation, and should include descriptions of any JC1 changes 
the operator has to make before running them; for example, how he 
specifies the log tape serial number. 

We recommend that all these jobs be set up and tested before you go into 
production mode. This setup would include preparing restart JCL for all 
BMPs, and data base recovery jobs for all online data sets. 

The sample NIC guide assumes that the method of online leg tape 
administration described in Chapter 6: "Recovery," is used in the 
installation. If you use a different scheme, you should modify the 
guide accordingly. 

2EJBlicatio£ -i ,0£jratiBC|_Piccedur€s 

Chart J-1 of the sample guide is an index to operating procedures for 
applicaticn programs. Sou should extend this section to include 
operating procedures for all applicaticn programs. 

TESTING THE MTO GUIEE 

Once you have prepared the BTC guide for your installation, all the 
operators who till be master terminal operators should be given an 
opportunity to familiarize themselves with it. After that, all the 
procedures in the guide should be thoroughly tested. Even if you use 
the sample guide, ycu should carry out the tests, to ensure that the 
procedures are accurate for your environment, and the operatcrs knew how 
to use them. 

These tests shculd be carried out in a controlled fashion. re 
Administration in conjunction with the Operations Department should 
prepare a detailed schedule, shewing what tests are to be done, how they 
are to be done, and what procedures in the guide they test. The tests 
should be designed in such a way that all the operating procedures are 
checked out. All operators should have an opportunity to perform all 
tests. In order to test some of the recovery procedures, certain types 
of system failures kave tc be simulated. Figure 8-2 shows a table of 
possible failures, and how they may be simulated. 

During the tests, the operators should write down which procedures they 
use, any deviations they were fcrced to make frcm the standard 
procedures, and any error messages they received that were not 
documented. After the tests have been run, a meeting should be held to 
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discuss the results. Any corrections should be made, and the procedures 
re-tested if necessary- 
after the initial testing cf the guide, the recovery procedures should 
be re-tested en a regular basis, say once a month. This is to ensure 
that the operators remain familiar with the procedures, and that no 
changes need to fc€ made. 

MAINTAINING THE MTO GOIDE 

It is vitally important to the successful running of the online system 
that the MTO guide be kept up to date, and that any errors or omissions 
in it are corrected. 

After the initial tests have been completed, a procedure should be set 
up whereby an operator who finds an error can document it to alert DC 
Administration. The progress cf the error correction should be followed 
up on a regular basis. 

As new applications, data bases, or terminals are added to the system, 
the configuration tables in the guide shculd be updated. The procedures 
should be re-tested and the guide updated if necessary, after a new 
release of IMS/VS cr OS/VS is installed. 



SYSTEM FAILCEE 

1. EMF abended or 
cancelled in error 

2. CTL region abended or 
cancelled in error 



| SIMULATED EY : 

Use MTO command 
/STOP REGION n ABDUME 

Ose OS/VS modify or cancel 
command 



3- MEP abended 



4. MPP looping cr in 
wait state 



5. I/O error on log tape 



Fun TEUCCNEW in test mode* 
reply 'ABEND' to DFS3125A 
message 

Bun IE4CONEW in test mode* 
reply •LCCE 1 to BFS3125A 
message 

Ose a log tape that has 
previously been mutilated 

Unplug/Switch off OS/VS system 
residence drive 

Unplug/Switch off OS/VS system 
residence drive 

Eress System Beset, and re-IPL 



6. OS/VS error (loop or 
abend) 

7. Hardware error, no 
loss of main storage 

8» Power failure, or 
hardware error with 
less cf main storage 
t --_ — ______ ______ — _ __ _ -__j 

* Transaction TEUCONEH in the sample system includes a testing 
cption which can be invoked by entering •!• in the CNG-FUNC 
field. Message DES2125A will be issued by the MFP. See the 
IMS/VS Messages and Codes Beference Manual for more details 
on this message and its allowed replies. 

Figure 8-2. Simulating System Failures. 
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Once ycu are familiar with the IMS/VS log tape restart operation, ycu 
should consider implementing IMS/VS disk restart. The reason we did not 
include it in our subset is that even with disk restart, proper handling 
of log tapes and loc tape restart is essential to a problem-free IMS/VS 
operation- The benefit of disk restart is that it reduces significantly 
restart time and operatcr tape handling. For mere information on disk 
restart, you should refer to the base IMS/VS publications. 

If ycu implement disk restart, you should at least: 

• Update your MIC procedures 

• Increase tbe space allccaticn of the disk restart data set IMSVS.RES 

DS!l_LIAISON_GROUP 

Depending on the number of users of the system, and the organization, 
the user liaison grcup lay consist of enly one person acting as a buffer 
between the remote terminal operators and the MTO or it may consist of a 
number of people, who resclve most user gueries themselves. 

People performing this function should have a good knowledge of terminal 
operating procedures, and a broad overview of all the applications. 
They should normally be able to diagnose a user*s problem to the extent 
of knowing whether to route the query to the MTO, Network Control, cr 
the appropriate Application Supervisor. In a large installation, 
members of this group might have their own terminals, and be authorized 
to use a subset of the master terminal commands, such as START, SIOP, 
DISPLAY, and ASSIGN. 

I1IH CJ;I_T I EMINAL_gPJBATORS 

The success of an online system depends largely on its acceptance by the 
users. To make it acceptable to these people, you must provide good 
training and documentaticn, sc that their interface to the system is as 
smccth as possible. The term "Remote Terminal Operator" or "RTO" is 
used to describe users of the online system, who may be operating lecal 
or remote terminals. The word "remote" is used to distinguish them from 
the Master Terminal Operator. 

TRAINING BEM01E TEBKINAI CPZBATCBS 

Generally, an RIO Guide, no tatter hew comprehensive, is not sufficient 
tc train new terminal operators who may not be familiar with computer 
concepts, and, in some cases, may not know the application either. We 
recommend that, as terminals are installed in departments for the first 
time, a training team be sent to provide initial user education. 

This team should consist of a person, or persons, who can give an 
introductory talk en computers, who knew how to operate the terminals, 
and who understand the applications and the transactions that will be 
used in that department. Ihis team should remain in close contact with 
these users until their initial problems have been overcome. 

A training program should also be set up within the department, so that 
new users can be trained by those already familiar with the system. 
This training program should be formalized to ensure that the education 
is done thoroughly. It may be possible to set up dummy data base 
records on which terminal operators can practise. If this is the case. 
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the procedures for them tc access these records shculd be documented in 

a training guide. 

THE FTO GUIEE 

This document should be supplied to all terminal users. The manual 
entitled IMS^VS - Erioer_£§mcte_Terminal_0£eratorJ,s_€uide is a sample of 
such a guide- ifce aim of this document is to provide a guide tc using 
the online IKS/YS system fcr a terminal user who is unfamiliar vith 
computers. However, it is not intended to be a self-sufficient 
education document for such a user, although it could be used as part of 
a training program. 

M0DIFICA1I0NS ZC 1HE SAHEIE FTC GUIDE 

If you wish to use this saorle guide in your installation, you will 
probably need to make some modifications to suit your environment. 

SJJJDSliSIJaJLTitles 

The guide refers to the function "User Liaison" as the contact point for 
any problems. If you dc not use this title in your organization you 
should replace the references with the appropriate name. A list of the 
names and telephone numbers of people in the User Liaison group should 
be filed with the guide* 

The guide refers to the fact that a subset of IMS/VS is being used. It 
is assumed that the standards we have recemmended for screen design have 
been adopted. If you do not follow these standards, the guide should be 
changed accordingly. 

Conversational Processing 

If you do not use conversational transactions in your system, you may 
wish to delete the references in the sample guide. This includes the 
description of conversational transactions in Chapter 1 and the 
operating procedures for conversational processing in Chapter 3. 

Tejj|i2al_0£er.ating_££ocedui. es 

In Chapter 2 of the saiple ETO guide, the operator is told to ask the 
supervisor fcr a copy of the IEH manual, OEerator_^s_Guid§_for_I.BJi_J270 
Information_Dis£lav._Sy.stems, GA27-2742. You~may wish'te select'from 
this lanual the appropriate sections for the type of terminal and 
keyboard being used, and include them in the guide itself. 

A££ii£§£i2D_£pe rating _frocedures. 

Chapter 5 of the guide describes the operating procedures for the saiple 
programs. You shculd extend this section tc include the operating 
procedures fcr the transactions used in your installation. We suggest 
that each terminal user be given enly the procedures for the 
transactions that she/he is, authorized to use. If possible, you should 
include with the operating procedures samples of the screen layouts. 
These can be produced by using the copy feature on a remote 3277 screen 
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if you have ore in your installation, or by using the output of the MPS 
generation. 

Elcblen_EeEgrting_ Procedures 

In Chapter 4 of the sample ETC guide, the operator is told tc ask the 
supervisor for a copy cf the IBM manual, IBM_3 270_IDS_-2_Problem 
P§t§£iiS§ti2U-§!iii§x GA27-2750, if the operator suspects that there is a 
hardware problem on the terminal. You may wish to select the 
appropriate sections of this manual for the type of terminal in use, and 
include them in the guide. 

Chapter 4 alsc describes the procedure to be used if the user has a 
problem. Generally they are told tc ask the supervisor to contact the 
user liaiscn group if they cannot overcome the problem themselves. 
Depending on ycur organization, you may wish to redefine the problem 
reporting procedure. However where many users are physically located 
close to each ether, one person should be designated as the interface to 
the user liaiscn group- This is to avoid the possibility of all users 
of the system trying to contact user liaison simultaneously after a 
total system failure. 

A supervisor requires additional information that is not in the sample 
ETC guide. All supervisors should be given operating instructions for 
any additional equipment, such as datasets or modems. Depending on 
their location, and the organization of the company, they may need to 
know how to call for IBM Customer Engineering support and any other 
suppliers involved in case of hardware errors. 

MAINTAINING THE ETC GUIEE 

In order to achieve and maintain an acceptance of the online system by 
the users, the ETO Guide must be accurate and up to date. This implies 
that any errors in the guide reported by the users should be carefully 
investigated and corrected in all ccpies of the guide. If a new release 
of IMS/VS is installed, the guide should be thoroughly checked, 
especially the section en IMS/VS error messages. 

VTAM AND IMS/VS CEEBATICN 

In our subset we consider the VTAM operation as an integral part of the 
IMS/VS operations. This implies that the MTO is also responsible for 
the VTAM operation. This assumption might not be valid for your cwe 
installation. Especially if multiple subsystems are using VTAM, you may 
prefer to assign the VTAM operation to the CS/VS system console 
operation or tc a special VTAM operaticn group- In that case, you 
should adapt this chapter and the operating guides to your own 
environment. In any case, proper communication procedures between VTAM 
and IMS/VS operations must be established. 
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CHAPTER 9. OPTIMIZATION 



In this chapter ve will present basic guidelines for the monitoring and 
optimizing of IHS/VS applications. The optimization we are concerned 
about is the performance optimization, that is, the optimal use of 
computer resources. 

This chapter consists cf tvc parts. Part 1 deals with the optimization 
of IMS/VS batch applications. Part 2 covers the optimization of the 
cnline IHS/VS system. 

JJS/VS^BATCg.OEFCEKASCJ^fCKIJCilNG 

There are numerous areas fcr optimization of batch applications using 
IHS/VS. The most important areas are: 

• Data base structure, that is, data base design optimization. 

• Physical data set attributes, that is, data set location and 
internal storage utilization. 

• Data base usage by the application programs, that is, DL/I call 
sequences. 

The first part of this chapter briefly addresses the above three areas. 
But before dcing so, we will take a closer look at the available tools 
for performance monitoring. 

The ultimate measure of performance is cost. This includes manpower and 
system cost. fie will consider only the system cost. The most important 
performance factors for DL/I applications are the number of physical 
I/Os and number of DL/I calls per transaction. CL/I provides two 
facilities to monitor these: 

« The DL/I buffer pool statistics 

• The DB monitor 

In addition, the standard CS/VS facilities such as SMF, GTF, etc., are 
cften very useful. 

THJ_£iZI_JUIIJl-PQQIj_ STATISTICS 

DL/I maintains statistics cr the use of its VSAM and OSAM buffer pools. 
These statistics can be obtained by your application program via the 
STAT call, as is done by subroutine DFSOAST in IHSVS.PRIMESRC. This is 
normally done at the end of each DL/I application program. Fcr more 
details on EISOASI and its use, see "The Stat Call" in Chapter 4. For a 
description of the VSAM and OSAM buffer pools, see "DL/I Data Ease 
Buffering Facilities" in Chapter 7. 
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THE VSAM EOFFEF POOL STATISTICS 

For each VSAM subpocl, DFSOAST prints 4 lines: 3 heading lines and the 
statistics. The format of the data is: 

B (J F F E B H A K D I E B STATISTICS 
ESIZ NEUF BET BEA BET KEY ISBT ES ISBT KS BFB ALT EGWBT SYN PTS 
nnnk nnn. nnnnnnn nnnnnnn nnnnnnn nnnnnnn nnnnnnn nnnnnnn nnnnnnn 

VSAM STATISTICS 
GETS SCHEFB FCUFE BEADS USB HTS NUB HTS EBBOBS 
nnnnnnn nnnnnnn nnnnnnn nnnnnnn nnnnnnn nnnnnnn nn/nn 

BSIZ = the size of the buffers in this subpool. 

In final total, this is the total size of all 

suhpccls. 
NBUF - the number of buffers in this subpool. 

In final total this is the tctal number of buffers 

in all subpools. 
BET BEA = the numter cf retrieve by BBA calls received by the 

buffer handler 
BET KEY = the numter cf retrieve by key calls received by the 

buffer handler 
ISBT ES = the number cf lcgical records inserted into ESDSs 
ISBT KS = the number of logical records inserted into KSDSs 
BFB ALT = the number cf lcgical records altered in this 

subpool 
EGWBT = the numter cf times the Background Write function was 

invoked by the buffer handler 
SYN PTS = the numter cf synchrcnizaticn calls received by the 

buffer handler 
GETS = the numter cf VSAM GET calls issued by the 

buffer handler 
SCHBFB = the number cf VSAM SCHBFB calls issued by the 

buffer handler 
FOUND * the numter cf tines VSAM found the control interval 

requested already in the subpool 
BEADS = the numter of times VSAM read a control interval from 

external storage 
USB HTS = the numter cf VSAM writes initiated by IMS/VS 
NUB HIS = the number of VSAM writes initiated in order to make 

space in the subpccl 
EBBOBS - the number of write error buffers currently in the 

sutpocl/the largest number cf write errors in the 

subpool during this execution 

Following are guidelines to the interpretation of the most icrportant 
fields: 

• Normally, 5CJE - 90* of the buffer handler requests (BET FEA ♦ BET 
KEY) would be satisfied from the pool (FOUND)- This parameter can 
be used to initially optimize the pool size. 

• The number of I/Os (BEADS ♦ USB HTS + NOB HTS) should be related to 
the number cf transactions processed by the job. An increase in 
this during production could be a signal for reorganization, 

• EBBOBS should be zero. If not, insure the data base is recovered. 
See Chapter 6, "Data Ease Becovery. " 
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THE OSAM EUFJER POOL STATISTICS 

If an CSAM data base used by the program, EFSOAST will also print the 
OSAM buffer pool statistics. 

The format of the data is as fellows: 

BLOCK FOUND READS BOFF OSAM 

EEC IN FOCL ISSUED HITS WRITES 

nnnnnnn nnnnnnn rnnnn nnnnnnn nnnnnnn 



WRITTEN LOGICAL 
AS NEW C1L FKT 
nnnnnnn nnnnnnn 

BLOCK REQ 
FCOND IN ECCI 

READS ISSCED 
EUFE ALTS 
OSAM WRITES 
BLOCKS WRITTEN 
NEW BLOCKS 
CHAIN WRITES 
WRITTEN AS NEW 
1CGICAI C*L FMT 
FORGE REQ. 
RELEASE REQ. 
RET EY KEY 
ISAM Gl NXT 

ISAM SETLS 

ERRORS 



BLOCKS 


NEW 


CHAIN 


WRITTEN 


BLOCKS 


WRITES 


nnnnnnn 


nnnnn 


nnnnn 


ISAM 


ISAM 




GT NXT 


SETLS 


ERRORS 


nnnnn 


nnnnn 


nn/nn 



PORGE RELEASE RET 

REQ. **C EY KEY 

nnnnnnn nnnnnnn nnnnn 



number of block requests received 

number of times the block reguested was 

found in the buffer pool 

number of CSAM reads issued 

nunber of buffers altered in the pool 

number of CSAM writes issued 

number of blocks written from the pool 

number of new blocks created in the pocl 

number of chained CSAM writes issued 

nuiiber of blocks written on OSAM chains 

number of logical cylinder formats 

nuirber cf buffer purge reguests 

number of buffer release reguests 

nuirber cf ISAM records retrieved by key 

number of ISAM get next calls received by 

the buffer handler 

number of ISAM SETLs issued by the buffer 

hardier 

number of write error buffers currently 

in the pool / the largest number of errors 

in the pool during this execution 



Note: Eecause ISAM is never used in our subset, its corresponding 
statistics should all be zero. 

Following are guidelines tc interpreting the most important fields: 

• Normally, 5CX - 90* of the blcck reguests received (EICCK EEC) would 
be served from the pool (FCUND IN FOOL). Also notice that, en the 
average, multiple blcck reguests are reguired for a single DL/I 
call. This parameter can be used to optimize the buffer pool size 
for the job. 

• The number of OSAM reads {READS ISSUED) and OSAM WRITES should be 
related to the number of transactiens processed by the job. An 
increase in these during production could be a signal for 
reorganization. 

• ERRORS should be zero. If not, insure that the data base is 
recovered. See Chapter 6, "Data Base Recovery." 

THE_IMS/VS_DB_MCNITCR 

The IMS/VS DB monitor is a tool for collecting performance data to 
investigate specific application designs, data base designs, and 
resource allocations. It consists of a monitor module and a monitor 
report print program. When activated, it analyzes and records the 
internal activities of the IMS/vS-DB system. The monitor report print 
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program is processed offline tc produce reports that summarize and 
categorize, at various levels of detail, the information recorded by the 
mcnitcr mcdule. 

The monitor mcdule collects data from IMS/VS control blocks during 
operation of the batch system (with minimum interference to the system) 
and records the data either on an independent data set or on the IMS 
log. The monitor remains resident in the partition/region, and is 
activated and deactivated through the system console. 

The following are recommendations for use of the DB monitor: 

• Collecting data -- the DB Monitor enables an IMS/VS user to collect 
performance data to assist in analyzing an existing IFS/VS batch 
system. Beports produced from profiles of a batch execution 
considered as ncrmal can be used as a profile and compared with 
reports produced during a batch execution with unusual performance 
characteristics. 

• Tuning system — the DB Monitor can be used to guantify the effect 
of actual changes to data base structures, program characteristics, 
data set placement and cool sizes. 

• Testing application — in the final testing of new or revised 
applications, the EE Monitor can be useful in validating the 
internal operation of the programs and data bases. For example, 
assume the programmer thought a specific DL/I call could be 
satisfied with a single I/O retrieval, yet the DI/I call report 
indicated a large data base scan as shown by many IWAITs. 
Investigation of such items could assist in determining whether a 
new or revised application meets the performance objectives. Data 
contained in the reports may also assist in defining the resources 
required by an application program. 

OSING THE IMS/VS DB MONITOR 

The DE monitor formats and records performance -related data during the 
execution of the IMS/VS batch system. The DB monitor can be active 
during the entire execution of the IMS/VS batch job or it can be started 
and stopped from the system console. Typically, activating the DB 
Monitor for 15 to 2C minutes is sufficient to collect representative 
data. 

£ctivation_and_Control 

Including the parameter KCN=Y in the PABM parameter of the JCL execute 
statement in the hatch procedure makes the DB monitor active when batch 
system execution begins- (See "The DLIBATCH Procedure" in Chapter 7, 
"Installing IMS/VS.") 

"DFS2216A MONITOR ACTIVE, MODIFY TO STOP MCNITOF" prints on the system 
console whenever the CE monitor is initialized or started. To stop and 
restart the DB monitor, the system console operator can, at any time, 
enter; 

MODIFY jchname,STCP (or F jobname, STOP) 

"DFS2215A MONITOR INACTIVE, MODIFY TO START MONITOR" prints on the 
system console when the IMS/VS DB monitor receives and acts upon the 
modify command. 
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To reactivate the DE monitor, the console operator enters: 

MODIFY jobname,STAFT (or F jorname, ST AFT) 

"DFS2216A MONITOR ACTIVE, KCBIFY TC STCP MONITOR" prints on the console 
and indicates that the modify command was accepted. 

The data produced fcy the DB monitor is recorded on either the IKS/VS 
system leg or on a separate EB monitor log* The presence or absence of 
a EE card named //IMSMON ir the batch procedure determines which log is 
used- If a //IMSMCN DE card is included (and does not specify DUMMY), 
it specifies a separate DB iccitcr log on which the DB monitor records 
are to be written. If there is no //IMSMCN DD card (or if the //IMSWCN 
DD card specifies DUMMY) , the EE monitor records are written on the 
IMS/VS system log. 

When a separate EE monitor log is used, the system console operator may 
want tc force an end-of-volume when stopping the monitor from the 
console. The modify command can be used tc accomplish this. 

MODIFY jcbname,STOPEOV (or F jobname,S10PEOV) 

If, fcr any reason, the EE monitor log data set specified on the 
//IMSMON EE card cannot be cpened, the message "DFS2217I UNABLE TC CEEN 
MONLCG, M0NI1CR UNAVAIIAEIE" is displayed on the system console. The 
batch execution continues, but the DB monitcr is inactive. 

If I/O errors are encountered on the DB monitor log device, the message 
"DFS2219I I/C EF5C5 CN BONITCE ICG, MONITOF TEFMINATID" is displayed on 
the system console. The tatch execution continues, but the DB monitor 
is inactive. 

Note: When SICEFCV is used, execution of the batch region does not 
continue until the succeeding CS/VS mount message is satisfied. 

UOPIII_Q25!55E^_lE£2Is 

If the jobname is entered incorrectly when entering the MODIFY command, 
an OS message inferms the cperatcr of the error. If some other error is 
made while entering the modify command, the message "DFS2218I MONITOR 
MODIFY SPECIFICATION INCORRECT" is displayed on the system console, 
follcwed by either EFS22 15A or DFS2216A (described above). 

EB MONITOR REP0R1 PRINT PROGRAM, DFSUTR30 

The DB Mcnitcr Report Frint program (DFSUTR30) is an offline utility 
that organizes, formats and prints performance related data collected by 
the EE Monitor during execution cf a IMS/VS batch job. The reports 
printed by this program are: 

Statistics from the VSftE and CSAM pools 

Program I/O 

DL/I Call Summary 

VSAM Statistics 

DB Monitor Overhead 
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Note: The DESUTB30 program is dependent upon the data records en the 
data set produced ty the DB Monitor- Eeccrds of various events are 
expected in pairs — a start-event record and an end-event record; 
events are not counted and reported unless both are received. 

The following are explanations of key terms used in the reports tc 
describe activities or subtasks in the IMS/VS partition/region. 

ELAPSEE TIME: Time recorded by the time of day clock, from the start of 
the activity or subtask until the end of the activity or subtask.. 

IWAIT: A wait for an I/C cr another resource which occurred during the 
processing of a EL/I call. 

IWAIT TIME: Elapsed tine, during which an IMS/VS subtask was inactive, 
waiting for a resource or the completion of an event. An exception tc 
this definition cccurs when the IWAIT time is related to VSAM activity. 
In this case, the IWAIT time is defined as the elapsed time between the 
entry to and the exit frcm the VSAM routines. Euring this VSSM time, an 
I/C access and wait may or may not have occurred. 

NOT IWAIT (ELAPSED TIME -- IWAIT TIME) : Elapsed time minus all IWAIT 
time identified for the subtask or activity. It includes any time spent 
by OS/VS, or by any other higher priority tasks running in the systems 
when the IMS/VS region was interrupted and dispatchable, and when the 
subtask to which the CPU time refers had been executing at the time cf 
the interrupt. Note that this may approximate total CPU time if the 
IMS/VS-DB region is the high priority task and if no lew priority tasks 
are causing interrupts. 

CPOTIME: Actual CPU time used by an application program. 

SCHEDULE TO 1SI DL/I CAII: Elapsed time accumulated for the following 
actions to occur: the region to gain control after being scheduled, 
plus the program either tc be located in the region by contents 
supervision of OS/VS, or to be brought in by program load, plus the 
program to issue the first DL/I call. 

ELAPSED EXECUTION TIME: Elapsed time from IMS/VS dispatch of the first 
DL/I call by a program until the IMS/VS termination cf that program. 

MAXIMUM TIME: Longest single time duration noted for an event- 

TOTAL TIME: Sum of all the time durations noted for a group of events. 

MEAN TIME: Quotient of the tctal time (above) divided by the number of 
occurrences of a certain event. 

ISEI KSES: A count cf the root segments inserted into a SHISAM data 
base or index data base. (This count should not be confused with the 
ISEI totals in the EL/I summary report.) 

ISEI ESDS: The number cf times the insertion of a root or dependent 
segment reguired a rew legical record for the new segment (SHISAM, 
HIDAM) . (This count should not be confused with the ISET totals in the 
EL/I call summary report.) 

Ufite: All the above tines are given in microseconds. 
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How^to^Execute^the^DE^Bonitor^EeEort^Print^lrogran 

Job //SAMP293 in IMSVS.PRIMEJOB shews the JCI to execute the EE Monitor 
Report Print Program, EFSUTR30-. The ANALYSIS DD statement should 
specify EOMMY,DCE=BLKSIZE=eC in our subset. 

This job prints the monitor output collected during execution of the 
customer order processing program with job //SAMP272. 

The output, which is listed in Chapter 3 of the IMS/VS Primer Sample 
Listings, will fc€ referred tc in the following discussion~of~the~various 
generated reports. 

Statis£ics_from_the_VSAM_and_OSAM_Bu 

These summary reports are formatted displays of the contents of selected 
statistics of the CSAM buffer pool and VSAM buffer subpool(s) that were 
collected for batch activity over the entire run of the DB Monitor. 

The peel ending values and the difference between starting and ending 
values cannot be computed for these summary reports unless there are 
pool ending statistics on the trace tape. Ihe OSAM buffer pool ending 
values are recorded only if the EE monitor is ended before the IMS/VS 
batch job is terminated. 

The following message is printed if the summary reports are not printed: 

NO DATA EASE EOIFER DATA AT END TIME ON MONITOR LOG TAPE: 
****DATA BASE EUFFER PCCI CA KCELLEE**** 

The VSAM Buffer Subpccl Suamary report is net produced if the VSAM 
facility is not invoked through the IMS/VS system definition or if the 
ending values are not written on the trace tape. In either instance, 
the following informaticn message is printed: 

NO VSAM EUFFER POOL TRACES ON MONITOR ICG TAPE: 
****VSAM EUFFEB FCCI FEFCBT CABCELLEE**** 

For an example of these statistics, see the sample output (pages 1,2 and 
3) cf job //SAMP 29 3 in Chapter 3 of the IMJ/VS Primer. Sample listings. 
For a description of these statistics, refer to the previous section" 
"EL/I Euffer Eool Statistics." 

Progr a m_I/C_ Report 

This is a summary report of the total and mean IWAIT intervals recorded 
for I/O IWAITs caused by DL/I calls by the program during the trace. 

The data is arranged by PCB name, ddname, and module identification of 
the mcdule that IHAITed. The data under the column heading "IWAITS" 
indicates the number cf times that DL/I calls for the associated PCB 
were required to wait for I/C activity to complete- The data set for 
which the I/O tock place is indicated by the ddname. Entries under the 
heading "Module" are abbreviated identifications for IMS/VS-DE modules. 
The cress-reference is: 

!££reviated_IE Mfidule^Name 

EEB EFSBEERO 

DLE DFSDDLEO 

VEH DFSEVSMO 

PCB subtotals and a batch tctal are provided. 
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For an example of this report, see the sample output (page 4) of job 
//SAMP293, in Chapter 3 cf the IMS^VS j? r ime r Samjale Listings. 

The two main effects to be noted from this report are: 

• If the number of IWAITS per transaction increases, it may be 
necessary tc reorganize the data set in guestion. 

• If two or more data sets with high activity are on the same disk 
drive, there may be a contention problem. 

2L/I_Cal^ - Summarv._EeEort 

This is a compact tl/I call summary report for the trace. All DL/I 
calls issued by the program during the trace are arranged as follows: 

« PCB name. 

• For each ECE, the call function employed. 

• For each call function, the segment accessed and its level number. 

• For each segment, the return cede obtained. 

For each line in this report, the number of DL/I calls recorded, the 

IWAITs per call, and both the average and maximum elapsed time and 

Not-IWAIT times are given. A batch total of DL/I calls is provided at 
the end of the report. 

For an example of this report, see the sample (page 5) output of job 
//SAMP2 93 in Chapter 3 of the IHS^VS Prifier. Saiple Output Listings. The 
column entries, from left to right, are: 

PCB HAME The 8-character FCE name. 

CALL FONC. The 4-character DL/I call function. 

LEV HO. lhe data base level number reached in this call, or 
blank. 

SEGMENT The 8-character segment name accessed by this call. 

STAT CODE lhe status cede returned by this call. 

DL/I CALLS lhe number of calls noted having the unigue 
combination of the above five attributes. 

IWAITS The ruttber of I/O WAITs observed for the calls. 

IWAITS/CALL Quotient of the above two items. 

ELAPSEE TIME For an explanation of these terms, see 
or NO! IWAIT "Definition of Terms Used in Reports" earlier in this 
chapter. 

The main effects to be noted from this report are: 

• If the number of IWAITs per EL/I call increases, this nay signal the 
reguirement for data base reorganization. 

• A relatively high number of IWAITS per DL/I call may indicate a 
small data base Cl/blocksize, or buffer pools that are too snail. 
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Unnecessary calls issued by the application program can be traced by 
checking the report with the program specifications and detailed 
flew. 

Calls with very high I8AIT counts may indicate insufficiently 
qualified calls, which result in data base scans. 

Note: Frequent IHAITs with a very long elapsed time may be a result 
of excessive paging or frequent de-activations. This should be 
discussed with the CS/VS system programmer - 



VSA!J - £tatis^ics_|epo£t 

This report (page 6) provides statistics on a per call basis for changes 
in up to 13 selected subpool statistics between the start and end of 
VSAM activity. The statistics reported are: 

Number of retrieves by RBA calls received by the 
buffer handler- 

Number cf retrieves by key calls received by the 
buffer handler. 

Number of logical records inserted into ESDSs. 

Number of logical records inserted into KSDSs. 

Number of logical records altered. 

Number, cf times background write function invoked. 

Number cf synchronization calls received by the 
buffer handler.. 

Number cf VSAM GET calls issued by the buffer 
handler. 

Number of VSAM SCHFR calls issued by the buffer 
handler. 

Number cf times VSAM found the control interval 
reguested was already in the subpool. 

Number of times VSAM read a control interval from 
external stcrage. 

Number cf VSAM writes initiated by IMS/VS. 

Number of VSAM writes initiated in the subpool. 

The report contains a set of the above statistics for each combination 
of PCB, call function and ddname detected in the trace- An occurrence 
count is printed. Each set cf statistics is a summation of the changes 
in all subpocls divided by the number of occurrences- Summary lines 
show totals for each PCB, fcr each ddname under the PCE # and for the 
ccnplete trace. 

21 !32£ii£f_£verhead_Beport 

Ihis report (page 7) provides the total elapsed time during which the DB 
Monitor was active and the tctal of the time intervals between entry to 
and exit from the DE Monitor module. The report also includes the 
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number of EE Monitor records that were written and the average DB 
Monitor time per entry. 

P2TA_E2SJ - .EJSIGN - gPlJMIZA2igM 

Because the data base design optimization should be started before the 
physical implementation, the previously discussed tools are not 
applicable. Instead, ve will introduce a simple paper and pencil 
technique to evaluate alternate designs- This technique will 
concentrate on the cumber of physical I/Cs, and the number and 
conplexity of Dl/I calls per transaction- This is because, as stated 
before, these two factors are the most important performance factors for 
data base processing. 

DATA BASE IOAE FACTCBS FEE TBSNSACTICN 

For all transactions, data base load factors can be established. A 
transaction lead factor represents the CPU power needed for the 
processing of that particular transaction. It is a relative factor, not 
an absolute one. Its sole role is to provide a base for cojfarison 
between alternative designs. 

Note: If more accurate performance prediction in the design phase is 
required, then design tools such as DBFRCTOTYPE/VS should be considered. 

Transaction^Load^Factcr^Onitj 

The table in Figure 9-1 gives basic estimates of transaction load factor 
units for DL/I calls or data base I/O. 
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A GO CALL 


1. 1 
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A EEPL CALL 


.5 


A I SET CALL 


I 1-7 


A DLIT CALL 


1.8 


EETBIEVE CF CNF SEGMENT 


I .5 


INSERT OF ONE SEGMENT 


2.4 


REPLACE OF ONE SEGMENT 


| 1.6 


EELETE OF ONE SEGMENT 


2. 1 


A D8TA BASE I/C 


! 5 



C------------------------------ — j 

Figure 9-1. Transaction Lead Factor Units 

The following considerations apply: 

«• A single EL/I call can incur multiple segment accesses, that is, to 
fellow a twin chain. 

• If HDAM, each access of a synonym on the anchor point chain is cne 
segment retrieve. 

■• If HIDAM, the access of the primary index data base should be 
counted as one additional segment access. 
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• For replace, insert and delete each segment occurrence to be 
processed must be counted separately. 

Exajfle 

As an example ve use the logical CUSTOMEB OBDEBS data base (Figure 
2*26). A GU call, for instance, to the third SE20PABT occurrence for a 
given customer order Mould cost: 



Segment accesses: 



Salts 



GU call 1. 1 

Betrieve of index pointer segment .5 

Betrieve of root segment . 5 

Betrieve of first, second ♦ third CBEEB LINE 

segment 1. 5 

Betrieve of logical parent, PABT segment ^.5 

subtotal U. 1 

I/Os: 

KSDS index component 5 

KSES data component 5 

ESDS for root segment ♦ dependents 5 

ISES of logical parent 5 

subtotal 20 

gross total 24.7 

Assumptions: 

1. The OBEEB LIVE segments are in the same CI as their root. 

2. None of the requested CIs is in the buffer pool. Quite often the 
I/O for the index component is not necessary. Also, for the get 
next call, most retrieves are satisfied from the pool. 

Gnce again, it should te realized that the above method gives only a 
rough estimate of the cost cf a particular call. Its main use is to 
evaluate possible alternative designs. 

DATA BASE DESIGN CHECKIIST 

The following checklist gives an overview cf the mcst important 
considerations/guidelines for data base design optimization. These 
considerations/guidelines are oriented towards performance. Sometimes, 
they will contradict application requirements. In such cases, a 
compromise must be made based on a cost/function analysis. 

• Use a structure no more complex than necessary. 

• Keep freguently accessed segments near the top and to the left cf 
the hierarchy. 

• Avoid widely varying segment sizes for volatile segments in the same 
data space. 
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• Check the requirement fcr any segment type whose relative frequency 
under its parent is one, or whose prefix length is greater than or 
equal to its data length. 

• Oversegmentaticn results in many DL/I calls and longer 
reorganization times. 

• Ondersegmentation results in less security and less data 
independence. 

• Avoid movement cf data from one data base to another. 

• Avoid secondary indexing on highly volatile source segments. 

• Use secondary indexing fcr alternate entry, not sequential 
processing. 

• If logical relationships exist, place the real logical child so that 
the physical path is the ocst active path. Also consider placing 
the real logical child on the longest twin chain. 

• Sequencing of the logical twin chain is expensive on insert and 
delete processing. 

« Avoid long twin chains, particularly logical twin chains. 

OPTIMIZ AT ION_Q!_PHYSICAL._IMP! ! E MENTATION 

Eecause DL/I data rases are stored in CS/VS data sets and/or VSAM data 
spaces, the ncrmal performance guidelines for these apply. In addition, 
the following considerations/guidelines should be observed. 

• Keep segments tc be accessed in the same block as the entry segment. 

• Use HCAH whenever possible. 

• Process HEAM data bases sequentially by inserting the randomizing 
routine into a sort exit and sorting into a root anchor point 
sequence. 

• GN processing at the root level in HTAM proceeds in physical roct 
anchor pcint sequence with synonyms maintained in logical key 
sequence off their root anchor point. 

• If root key sequence is required in HCAH, consider a secondary index 
(for limited use) cr a randomizing routine which assigns root anchor 
pcint addresses in key sequence. 

• The expected I/Cs required to access a HDAM root with a general 
randomizing module, is between 1.1 and 1.2 if the number of roots 
per block is 5 or more and the block and the RAP densities are less 
than 80*. 

• Dc not specify twin backward pointers for HDAM roots. 

• Specify PTB=TE or none (ST) for the HIDAM root seqment. GN 
processing at the rcct level in HIDAM proceeds along the physical 
twin chain if IB has teen specified, or via the index if not. Note 
that a GN root with key qualification always proceeds via the index 
if the call cannot be satisfied at the current position. 

• Specify TE pointers en segments to be deleted to improve delete 
performance for long twin chains (that is, more than 3 to 5) . This 
is particularly important for the logical child segment. 
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Specify LCL in the logical parent and LTE in the logical child if, 
on averag€ r there are sere than 2 logical children per logical 
parent. 

Co not define a sequence field for the virtual logical child, unless 
really needed. 

Check report from data base unload to identify long twin chains. 

For insert activity against a HIDAM data base, specify free space in 
the EEE. 

The HIDAM primary index should be reorganized frequently to minimize 
I/C and regain space from deleted entries. 

Leave sufficient free space for anticipated inserts prior tc 
reorganization. 

HE free space within the blcck should be large enough for the 
largest segment type. 

When defining KSDS data sets, select the IMBEE and replicate options 
and provide free space fcr insert activity. 

For initial load select speed option in VSAM define. Specify 
INSEE1=SEC in the EFSVSABE EE * data set for initial load cr any 
mass insert after initial lead to maintain KSDS free space. 

To insure that KSDS index control intervals remain in main storage, 
provide a unigue control interval size (1K is a good number) and 
provide enough buffers to hold all index set CIs plus at least one 
seguence set CI for each KSDS. Bemember that seguence set and index 
set CIs contend fcr buffers in the same shared resource subpool on a 
demand basis. 

• VSAM buffer pools and/cr ccntrol blocks can be page fixed in main 
storage by specifying VSAMFIX= (BFR,IOB) in DFSVSJME data set. 

CPTIMIZATI01i-OI-lP£IiICATICN_PROGEAMS 

In general, the rumber and complexity of DI/I calls determine to a large 
extent the performance of a Dl/I application program. The following 
considerations/guidelines shculd be observed: 

Eeduce the tctal number of calls to DL/I by using path calls and 
more fully qualified SSAs. 

Save data in virtual stcrage rather than reissue calls. 

Do not issue a get call prior to ISET to check for prior existence. 

Use multiple PCBs when referencing data in two parts of the data 
base oi data base record. 

Sort batch transactions to natch the physical order of the data 
base. 

^Tj;j££2II<i_TJ3_JMS/VSJ>HLJN£_SJ$IlM 

The means to optimize an IMS/VS online system are essentially the same 
as discussed for the batch-only system in the first part of this 
chapter. The two key performance factors introduced in that part, the 
number of DL/I data base calls and the number of physical I/Cs, retain 
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their significance. They are expanded here to include DL/I message 
calls and physical I/Os fcr the data communication lines, the message 
queues, and other data sets used by the online system.. 

CN1INE_PEFFCBKANCZ_FCNI1CBIKG 

The online IMS/VS system contains several tools tc monitor its 
performance. Those used ircst often ace: 

« The online buffer pool statistics, which can be requested at regular 
time intervals by the master terminal operator (MTO) . 

• The log data set statistical analysis utility. 

• The DC monitor and its DC monitor report print program. 

In addition, the standard OS/VS facilities such as SBF, GTF, etc., are 
cften very useful. 

IHE^ONLINE.EDFFEE^ICCl.STflTISTICS 

The online buffer pool statistics provide information on the usage cf 
the IMS/VS data and ccntrcl blcck buffer pools. These statistics are 
displayed as a result of the /DIS FCOL ALL command on the master 
terminal. See the MTO Guide fcr more details en how to use this 
command. All displayed counts are relative to the last (re) start of the 
IMS/VS control regicn; all counters are reset to zero during restart 
processing. In general all counts should be related to the number cf 
messages or transactiens processed. 

N_c_te ; Performance interpretation, especially cf the number of physical 
I/Cs, should not be based on a short session. The number of I/Cs will 
be relatively high during the beginning of a session because initially 
all needed ccntrol blccks must be read in. It is therefore recommended 
that you disregard the first half hour of a session. 

The following sections briefly discuss the statistics for each peel and 
give guidance for their initial interpretation. Figure 9-2 shows the 
format of these statistics as they appear on the 3270 display screen. 
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'"v MESSAGE QUEUE POOL 
ENQ 95 DEQ 



BFRS/SIZE 10/1500 
90 CAN 55 WAIT 
MESSAGE FORMAT POOL: SIZE 204 80 SPACE 17192 



I/O 



8 ERR 



REQ1 193 I/O 13 DIR 5 WAIT 

DATA BASE BUFFER POOL: BSIZE 1024 

RRBA RKEY BFALT NREC 

NMBUFS 12 VRDS 6 FOUND 20 VWTS 

DATA BASE BUFFER POOL: BSIZE 2043 

RRBA 98 8 RKEY 8 BFALT 4 5 NREC 

NMBUFS 2 VRDS 171 FOUND 3 02 VWTS 



DISPLAY LINES WAITING 



13 FREE 13184 ERR 

SYN PTS 1 1 
ERRORS 00/00 

12 SYN PTS 11 

13 ERRORS 00/00 

PASSWORD: 



/dis pool all 



DATA BASE BUFFER POOL: BSIZE 



RRBA 98 8 RKEY 
NMBUFS 3 2 VRDS 
DMBP BUFFER POOL: 
SIZE 8192 FREE 
PSBP BUFFER POOL: 
SIZE 20480 FREE 
CIOP BUFFER POOL: 
SIZE 40960 FREE 
MAIN BUFFER POOL: 

/dis pool all 



8 BFALT 
177 FOUND 

5936 HIGH 



53248 

4 5 NREC 
322 VWTS 

2256 



9648 HIGH 10832 



7568 HIGH 37440 



12 SYN PTS 1 1 

13 ERRORS 00/00 



DISPLAY LINES WAITING 



PASSWORD: 



SIZE 12288 FREE 
CWAP BUFFER POOL: 
SIZE 12288 FREE 
PSBW BUFFER POOL: 
SIZE 4096 FREE 
DBWP BUFFER POOL: 
SIZE 4096 FREE 
♦78180/213051* 



/dis pool all 



7768 HIGH 



12048 
4096 



HIGH 



HIGH 



4096 HIGH 



4616 



2632 



1576 



280 



PASSWORD: 



Figure 9-2. Online Pool Statistics Display Format 
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MESSAGE CUEOE IOCL 

The message queue pool statistics provide the number of messages 
received and sent. The following parameters are displayed: 

BFES/SIZE: The first value is the number of buffers. The second value 
is the si2e of a single buffer , as defined in the IMS/VS system 
definition. 

ENO.: Is the number cf messages enqueued in the input/output message 
queue. 

DEC,: Is the number of messages dequeued from the message queue after 
their processing cr trarsmissicn to their destination. 

CJ&N: Is the number of messages cancelled. A message is cancelled if 
rejected as an invalid transaction or during processing of some 
commands. This figure is typically very low. 

WAIT: Is the number cf I/C waits issued- This figure should be low 
[<\Q% of ENC.)- If not, ycu may want to increase the number cf gueue 
buffers. 

I/O: Is the number of physical I/Os against the message gueue data 
sets. This figure should be typically less than or equal to the ENC. 
figure. If higher, you may want to increase the number of gueue 
buffers. 

N c te s : 

1. The number of I/Os includes the I/Cs needed to format/restore the 
queues during IKS/VS (re) start. 

2. The number of queue buffers as defined at system definition can be 
overridden via the QB0F = parameter cf the IMS online procedure. 

EBB: Is the number of I/O errors for the message queue data set. This 
should be zero. If not, it is recommended to do an emergency restart 
with BOILDC or a cold start as soon as possible. 

MESSAGE FCBKAT ICCL 

The following parameters for the MFS buffer pool are displayed: 

SIZE: Is the total size in bytes of the MFS buffer pool. 

SPACE: Is the available space in the MFS buffer pool. This is the SIZE 
minus the space needed for the directory index, DCBs, pool control 
blocks, and the fetch reguest elements (FEEs) . One ERE of <40 bytes is 
required tc store a MFS format block in the pool. 

BEC.J: Is the number of block requests from the pool. Such requests are 
made for MIDs, MOEs, DIFs, and DOFs needed by MFS processing. 

I/C: Is the number of physical I/Os to the IMSVS. FORMAT data set. If 
more than 5036 of BEC.1# you should consider increasing the MFS buffer 
pool size. 

DIB: Is the number of directory I/O operations. This should be very 
low in the sample system because we will make the directory index 
resident during MFS processing. This is done with the MFS service 
utility. See "MJS Ccntrcl Block Generaticr" in Chapter 3, "Data 
Communication Design," and job //SAMF425, last step, in IBS VS. FBI ME JOE. 
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Mhll' Is the number of immediate fetch I/Os for the IMSVS. FORMAT data 
set. If nor€ than 50% cf 5EC.1# ycu shculd: 

1. Check if your MIDs refer to their corresponding BODs (NXT=parameter 
in the HSG statement) whenever possible. 

2. Consider increasing the size of the NFS buffer pool. 

FRJE: Is the amount cf free space in the peel. If this amount is 
constantly above, say 2K, in your production system, you may want to 
decrease the MFS tuffer peel size. However, a constant high value may 
also indicate too feu FREs, which means the available space cannot be 
used. 

ERE: Is the number cf I/O errors for the IMSVS. FORMAT data set. This 
shculd be zero. If not, you should restore the MFS library. 

Rote: Because the IMSVS. FCBKAT and IMSVS. FEFEBAL data sets are standard 
OS/VS partitioned data sets, normal library back-up and restore 
procedures can be used. However, they must be dumped and restored at 
the same time. Two sample procedures, MFSEACK and MFSREST, are provided 
in IMSVS. PROCLIE. 

i£justins_MFS_Buff er_Pco2_ Specif ications 

Luring IMS/VS system defiriticn, we specified a MFS pool size of 18K and 
a number of FREs of 40. You can change these values in the IMS/VS 
control region procedure. See the IMS procedure in Chapter 7, 
"Installing IMS/VS." The parameter FRE specifies the number of fetch 
reguest elements. The parameter FBF specifies the number of IK blocks 
in sutpool to he allocated to the MFS buffer pool. 

EATA EASE EOIFER POOLS 

Separate statistics are displayed for: 

• The OSAM buffer pool (not shown in Figure 9-2) 

• Each VSAM subpool 

• The combined VSAM pool, that is, the total of the VSAM subpccls 

SIZE: Is the total pool size in bytes for the OSAM buffer pool. 

JFECJ: Is the suiter of internal DI/I reguests to the pool. 

EEC.2: Is the numter of atcve reguests satisfied from the pool, plus 
number of new blocks created. 

READ: Is the number cf CSftK reads. 

BISAM: Shculd be zero, because we are not using ISAM. 

W£I2Ii : Is the number of CSAK writes. 

KEYC: Should be zero, because we are not using ISAM. 

LCYL: Is the number of CSAK logical cylinder formats. 

PORG: Is the number of synchronization calls received- 

CHNRE: Is the number of release ownership reguests. 
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EBBOBS: number of permanent errors (that is, blocks subject to a write 
error) now in the pool/total of these since last IMS/VS start-up. Ihis 
should be z€rc. If net, shut the system down as scon as possible and 
recover the affected data base. 

BEEA: Is the number cf retrieve by BEA calls (direct retrieves) 
received by the buffer handler. 

BKEY: Sam€ as afcove fcr retrieve by key. 

HALT: Is the number cf logical records altered. 

UJJC: Is the number of logical records inserted into ESDS/KSDS. 

SYNJPTS: Is the number cf synchronization points that involved this 
(sub) pool. 

Hl!i^l!J : Is tfte total number of buffers in this (sub) pool. 

VEDS: Is the number of VSAK reads. 

FOUND: In the number of requests (BFEA+BKEY) satisfied from the peel. 

VWIS: lotal number of VSAK writes. 

EEBCBS: Same as before. 

DMBP BDFFEB POOL 

Ihis pool contains the DKEs, which are the expanded DBDs of the data 
bases used by the ccntrcl region. DMBs are loaded from the IKSVS. ACELIE 
during CIL region initialization when defined as resident during IMS/VS 
system definition cr during data base open processing. Data bases are 
opened during the processing cf the first DL/I call against a ECE which 
references the data base. 

SIZE: Is the size in bytes of the pool. 

FEEE: Is the available free space in the pool. 

HIGH: Is the maximum amount of space used in the pool since the last 
CIl~region start-up. 

££J!lsting_the_DKEE_iool_Size 

The need to increase this peel can best be interpreted from the EC 
Monitor report. See its description later in this chapter. If the HIGH 
value in your production system is constantly 2K or more below the SIZE 
value, consider decreasing the EMBP pool size. This pool size is 
specified in 1K blocks Jrcunded to the OS/VS page size) in the DMB 
parameter of the IMS/VS control region procedure. See the IPS/VS 
procedure in Chapter 1, "Installing IMS/VS." 

PSBP BUFFEB PCCL 

This pool plays the same role fcr the PSBs as the DMBP pool does for the 
DMBs. The same considerations regarding its size apply. However, 
because PSBs are typically between 2 and 8K you should be careful in 
adjusting the size downwards based on the difference between the SIZE 
and HIGH values. For instance, if this difference is UK, you might 
still be swapping two 6K PSBs. 



S.18 IMS/VS Primer 



Note: The size of the PSBs is listed by the ACBGEN utility in message 
DFS940I. See the output of job //SAMP42 in Chapter 3 of the IKSIVS 
l£ilil JiSlli iiftings manual. 

The DC Monitor REGION IWAIT report lists the number of PSB loads- The 
corresponding parameter in the IMS/VS control region procedure is PSE. 
See the IMS/VS procedure in Chapter 7, "Installing IMS/VS." 

CI OP BUFFER FOOL 

This is the communication line buffer pool. The SIZE, FREE, and HIGH 
numbers have the same leaning as for the EMEP pool. Also, the same 
considerations regarding adjusting its size apply. The corresponding 
IMS/VS control region procedure parameter is TPDP. See the IMS/VS 
procedure in Chapter 7, "Installing IMS/VS." 

MAIN EUFFFR POOL 

This is the working storage pool, defined as WRAP in the IMS/VS 
procedure. Monitoring and adjusting its size is as previously discussed 
for the EMEP. 

CWAP EUFFER POOL 

This fcol is used to buffer the SFAs of active conversations. 
Monitoring and adjusting its size is as previously discussed for the 
EMEF. Its size can b€ changed via the CWAP parameter in the IMS/VS 
procedure. 

Note: The system definition value of the GENERAL parameter in the 
EUFPOOLS statement is used as the default value for both the MAIN and 
the CWAP buffer pool. 

FSEW E0FF1R POOL 

This pool is used mainly to process segments between the CTI and 
dependent regions. Monitoring and adjusting its size is as previously 
discussed for the EMEP. Its size can be changed via the PSBW parameter 
in the IMS procedure. 

DBWP BUFFER FCCI 

This pool is used for data base OPEN/CLOSE processing. Monitoring and 
adjusting its size is as previously discussed for the DMEP. Its size 
can be changed via the DEWE parameter in the IMS procedure. 

STATISTICAL. AJAIJSIS^JJIIIITY 

The IMS/VS Statistical Analysis Utility provides statistical information 
about online IMS/VS operation. Its information is obtained from the 
online IMS/VS log data set. The utility consists of three basic 
modules, EFSISTSC, DFSIST2C, and DFSIST30, and two intermediate sort 
steps. A sample job stream is listed as job //SAMP495 in 
IMSVS.PRIMEJOB. The sanple cutput is listed in Chapter 3 of the IMS/VS 
lEilSE Sample Listings and is discussed later in this section. 



Optimization 9.19 



JCL CONSItERAIIONS 

The following should be observed when using the JCL of //SAKP495. The 
numbers refer to the JCI statement numbers in the job listing. 

8. The SORT/MERGE program is used in all three steps with an entry 
point of SORT. 

12. ICGIK defines the ies/vs system log. Multiple volumes and data 
sets can be ccrcatecated if desired. 

14. The space parameter of this data set may need to be increased 
if the log data set reflects a large number of transactions. 

32,50. The estimated rumber of sort records in the SIZE parameter may 
need to be increased, depending en the number of actual input 
log records. 

50. The LINECNT parameter can be used to adjust the number cf print 
lines per cutput page. 

REPORT OUTPUT AND INTERPRETATION 

Six types of reports are printed by the statistical analysis utility. 
Refer to the cutput cf jcb //SAHP495 as listed in Chapter 3 of the 
IJSiJZVS Primer Sample £i§ting§ when reading the following sections. 

5S§§S3S§-Q3iSS^-lS^-^2i-S€nt_Jb^_destination)_ 

The number of not-yet-sent output messages per logical terminal (if 
known) is listed. 

Line_ an d_ Terrain a l_Rej3cr.t 

This report lists the message traffic received (R) or sent (S) by IMS/VS 
for each line, physical terminal, and logical terminal. An hourly 
distribution is given. 

Messages Queued But Net Sent fby transaction cede) 

The number of not-yet-sent output messages per transaction code is 
listed. A transaction cede of IMSSYS is listed if the output was 
generated by IMS/VS itself. 

3ranjsacticn._Rec.or.t 

This report lists the cuiber and distribution cf messages per 
transaction cede. 

3l§SS§Sii£B-S§IE2£iS-iSE2£i 

This report lists the response distribution per transaction code. Two 
response times are measured. The first line is the response time from 
ccmplete receipt of the input message until the response message to the 
terminal is completely received by the terminal. The second line is the 
response time from complete receipt of the input message until the 
sending of the response lessage to the terminal is started. nX response 
means that nX of the messages had a response time less than or egual to 
the listed nuiber. 
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Note: The actual figures of the sample output in Chapter 3 of the 
SEIZES £liMI Samjle listings should not be used for performance 
analysis and prediction, This is because the sample output vas 
collected during a test run under VM/370. 

This report lists for each program and transaction code the nuirber of 
messages and the average number of DL/I calls per message. The "CC or 
EC" column lists the number of times an application program teriinated 
abnormally, or returned with ether than zerc in register 15. 

The two last columns list the total and average CPO task time of the MPE 
region/partition. This includes the majority of the data base call 
processing. 

THJLEC_MONITOR 

The IMS/VS DC Monitor formats and records performance related data 
during the execution of the IMS/VS DB/DC system. 

The EC Monitor can be available but inactive and cause no increase in 
CPU utilization. Including a DO card, described below, in the procedure 
makes the DC Monitor available. The Monitor remains inactive, however, 
until started from the master terminal by a /TRACE command. 

The DC Monitcr reguires its cvr recording data set. Therefore a DD card 
<DENAME=IMSMON) must be included in the IMS procedure to describe and 
specify the monitcr log data set. If this card is not included, the 
Monitor will be unavailable. 

USING THE DC MONITOR 

It is, in general, not necessary to have the DC monitor active all day. 
A useful monitoring technique is to obtain "snapshots" on the Monitor 
log. Normally one tc three hcurs cf menitcring collects sufficient 
information for an entry system. 

I/C_Error: If a permanent I/C error occurs on the EC Monitor leg data 
set7""the~Monitcr stops and tfce message "DFS2202 UNCORRECTABLE I/O ERROR 
CN IMSMON" is displayed at the master terminal. In this situation the 
Monitor cannot be restarted until IMS/VS is restarted, and the DC 
Monitor log data set is only clcsed when IMS/VS is shut down. 

If the problem that caused tfce error has not been corrected when IMS/VS 
is tc be restarted, a different volume and/or unit should be specified. 

Starting - and - Stop£ing_the_EC - Jonitor 

Once the IMS/VS CTL region is started, the DC Monitor can be activated 
with the following command frcm the master terminal: 

/TRACE SET ON MONITOR ALL 

To stop the Monitor, enter: 

/TRACE SET Oil MCNITCR AIL 
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DC MONITOR REPORT PRINT PROGRAM, DFSOTR20 

The DC Monitor Report Print program (DFS0TR20) is a batch program that 
takes the data collected fcy the DC Monitcr (DFSMNTRO) and prints summary 
reports and distribution disclays of the data. The report formats, and 
the nature of information in the reports are identical or similar to 
those printed fcy DFSUTR3C, the Monitor report program. The values shown 
in the report samples are not intended to reflect actual values that are 
received fcy a user's execution cf this utility. 

The following types of reports produced by DFSUTR20 are of interest to 
the first -time user: 

• System conf iguraticn (data about OS/VS and IMS/VS systems used) 

•• Statistics frcm buffer cools (data collected at beginning and end of 
trace) 

• Region (data on timing, IWAITs, and CL/I calls presented fcy regicn) 

Regicn Sumarary -Regicn IWAIT 

• Program (data en timing, IWAITs, DI/I calls, scheduling and 
degueueing that is presented fcy an application program) 

Programs by Region -Program Summary -Program I/O 

• Communication (data on communication subtask timing, IHAITs, 
transmitted and received blocksizes, intersystem traffic and 
gueueing) 

Communication Summary -Line Functions -Communication IHAIT 

• Transaction gueueing (data en gueue lengths and scheduling 
occurrences presented fcy transaction type) 

• DL/I call summary (statistics on all DL/I calls issued by every 
program) 

• Run profile, an over-all picture of IMS/VS performance during the DC 
monitor trace interval 

For a description of the terms used in the report, see "Definition cf 
Terms Osed in the Reports" earlier in this chapter. 

Note: The reports contain a rich variety of data, much of which can be 
interpreted only with detailed IMS/VS knowledge. 

Therefore, we will enly discuss those cf immediate importance to the 
first-time user of our subset. 

How_to_Execute_the_EC_KonitO£_5e£ort Print_Pr_ggram 

Job //SAMPHSU in IMSVS.PRIMEJOB shows the JCL tc execute the EC Monitor 
Report Print Erogram, EISDTB30» This job prints the monitor output 
collected during the execution cf the IMS/VS CTL region. 

The output listed in chapter 3 of the IMS/VS Primer Sample Iistinjgs, 
will be referenced in the following discussion of the various generated 
reports. 

If the EC Monitor dees net collect certain types of information usually 
found in a particular report, that report, or the section cf that report 
that would normally contain the information, is not produced. For 
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example, if no checkpoints occur, only the headings for checkpoint are 
printed. 

Note: The page numbers listed in the heading of the following sections 
refer to the page numbers in the sample output of job //SAKP49U in 
Chapter 3 of the IMS/VS Frimer Sample listings. 

STATISTICS FRCM EUFFEB FCCLS REPORT 

These summary reports are a formatted display of the contents of 
selected items of the message queue, data base buffer pool, VSAM buffer 
pcol and message format buffer pool that were collected at the beginning 
and end of trace. These reports are preceded by a system configuration 
report (Fage 1) , which gives information about OS/VS and IMS/VS systems 
used. 

Since the pool ending values and the difference between starting and 
ending values cannot be computed if no pool ending statistics are 
written on the trace tape, this summary is produced only if the Monitor 
is ended before termination of the IMS/VS control region. 

In the case where only the ending values of one buffer pool are not 
written on the trace tape, the corresponding summary report is not 
computed and the following information message is printed: 

NO QUEUE EUFFER POOL TRACES AT END TIME ON MONITOR ICG TAFI 
****QUEUE EUFFEB ECCI REFCFT CANCELLED**** 

The VSAM buffer pool summary report and/or the message format buffer 
pool report will not be produced if the corresponding facility is not 
invoked through IMS/VS system definition- In this case, the following 
information message is printed: 

NC VSAM EOFFER POOL TRACES ON MONITOR ICG TAPE 
****VSAM EUFFEB PCCI BEFCBT CANCELLED**** 

The final number of this report (CUCTIENT) is the most interesting. 
Generally, in an entry IMS/VS system this number should be less than 1. 
If higher than 1.5, you should consider increasing the number of online 
queue buffers via the C.BUF parameter in the IMS control region 
procedure. 

Cat a_Jas€_BuJfGr_JSub|_jccl5. £ _Pa.ge£_3 i _a and_5 

The statistics of the data base buffer (sub) pools and their 
interpretation are the same as discussed in the first part of this 
chapter for a batch application. 

Mesgajge^Foimai^Buf fer_Pc£l Jt> _Pajgj|_6 

The final number of this report (QUOTIENT) is the most interesting. 
Ideally, in an entry IMS/VS system, this number should be less than 1. 
If higher than 4, ycu should consider increasing the size of the online 
MFS pool, via the FBP parameter in the IMS control region procedure. 
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SfaifiU-Sufffl§r^_Be2ort x _|age_7 

Region timing information is printed for every MPP/BMP active during the 
trace. This summary repcrt distinguishes the following activities per 
region: 

Scheduling and termination 

Schedule tc first DL/I call 

Elapsed execution 

DL/I call 

Idle for intent 

Checkpoint 

Region occupancy 

It should be noted that some of the values shown for region timing 
overlap in the timeframe of the trace period. Ilapsed time for 
scheduling and termination are included in idle-f or-intent time. The 
elapsed time for execution includes the elapsed time for DL/I calls. In 
general, the trace time period is slightly greater than the sum of 
scheduling and termination, schedule to first DL/I call, elapsed 
execution time, and idle-fcr-intent time. Differences between this sum 
and the trace time can be attributed to transactions active at the 
startup and shutdown of the tracing, or idle regions at the start or end 
cf a trace. 

SSlifduling and Termination: Lines under this heading, for each region, 
show the number of occurrences of scheduling and termination in the 
region, and both the elapsed execution time and not IWAIT time 
associated with scheduling and termination. The total of all intervals, 
the maximum single interval, and the mean interval values are shown. 

The elapsed tise during which the scheduler is internally waiting is not 
included in the elapsed time shown for scheduling and termination. 

This line of the repcrt dees net include data for a message regicn that 
was not scheduled hut was executing at the start of the trace. 

Schedule tc Firjjjt £L/I Call: The lines under this subheading show the 
elapsed time for the following to occur: the region to gain control 
after being scheduled; the program either to be located in the region or 
to be brought into the regicn; or the program to issue the first EL/I 
call reguiring dispatching of the IMS/VS Call Analyzer Module. 

This section does not appear for a message region or a batch message 
region that was not scheduled during the trace; it does not appear for 
cne that was scheduled but did not issue a DL/I call following the 
scheduling. The number cf program loads is one less than the number of 
schedulings, if the trace was ended after the scheduling hut before the 
first DL/I call of the last scheduling. 

Il§£§§<l il§2utio^: Lines under this subheading give the number of 
executions of programs in each region and the elapsed time for each 
execution. 

The number of executions say be one less than the number of schedulings 
and schedule tc first DL/I calls if the program that was scheduled had 
an outstanding DL/I call when the trace was ended. 
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DL/I Call: Lines under this subheading give the total number of DL/I 
calls from each region during the trace, the total, nean and maximum 
elapsed execution tine intervals to complete those calls, and the total, 
mean and maximum non-IKAlT intervals used to complete those calls. The 
number of IHAITs per call is computed and displayed for each region 
under the heading "IHT/CAII. " 

3s!l§ I2E ISl£St : lines under this subheading give the number of times a 
region was in the idle state because of an intent conflict. An intent 
conflict occurs during scheduling when the program to be scheduled needs 
data base resources held by another active program. See the section 
"Data Base Processing Intent" in Chapter 3, "Data Communication Design." 

Checkpoint: This line is produced if a checkpoint occurs during the 
trace." " 

The line gives the number of times checkpoint was dispatched, the total 
elapsed time of the checkpoints, the mean elapsed time for a checkpoint, 
and the maximum of those elapsed times. 

The line also gives the total non-IWAlT time for the checkpoints, the 
average non-IWAIT time for a checkpoint, and the maximum of those 
ncn-IHAIT times. 

Begicn_Cccuc.anc2 

lines under this sub-heading indicate the percentage of time that the 
region was occupied. This value is determined from the formula: 

scheduling + termination -(-schedule to 1st DI/I call 

Begicn Occ upanc y= _^ !_£rgsr am_elaEsed_jf_idle- f or-intent 

trace elapsed time 

The value of trace elapsed time is the difference between the time 
recorded for the first traced IHS/VS event and the last traced IMS/VS 
event. 

JSSio£_IHiIT x _£ac,€s_8 x _9 

This report lists the occurrences and duration of IHAITs for each 
dependent region during: 

• Scheduling and termination processing 

• DL/I call processing 

• Checkpoint processing 

CCCDBEENCES: Lists the number of IHAITs 

TOTAL x MEAN A _MAXIKUM: Lists the total, mean and maximum elapsed time of 
IHAITsT 

FUNCTION: Lists the cause of the IHAIT. PSB/DMB defines the ESE/EEE to 
be loaded, DC defines the data set via its DDNAME which needed an I/C. 
If the number of ESE/DKE loads (IHAITs) is high, you might consider 
increasing the PSE and DMB pool sizes. 

MODULE: Defines the module involved in the I WAIT. BLB = block loader 
for~PSBs, DMEs. VBH ■ VSAM buffer handler. QMG * gueue manager. 
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This report lists an overview of the most important factors for each 
MFP/EMP activ€ daring th€ period of monitoring. The time figures are 
given in microseconds. The columns and their meaning are: 

1?£±~C]!££.§« T ^ € number cf scbedulings. 

TEANS..DEO,: The number of input message dequeued after their successful 
processing by the program. 

JCL/I_C^LLS: The total cumber cf both message and data base calls issued 
by the program. 

DL^I_CALLS^IBAN: Same as above, but per input message. 

I^O_IHAITS: The number of I/Cs required by IMS/VS to process these DL/I 
calls." An average telcw two is preferable. However, higher values 
cccur if the processing cf a call involves scans of long physical twin 
chains or insert/deletes of segments involved in logical relationships 
and/or secondary indexes. 

THAN, DEQD/SCH: The average number of input messages (same transaction 
code) processed in one scheduling of a MEP. This number in our subset 
is between 1 and 5. 

CPJLTIME^SCHEr: The average CPU task time for the MPP/BMP region per 
schedule. This will be typically very high for EMPs because the full 
processing of a BMP constitutes one scheduling. 

ELAPSED TIME/SCHED: The average program elapsed executing time per 
scheduling." ThTs~"number is largely dependent of the processing 
performed by the program, especially its number of DL/I calls and 
associated I/Os. Ideally, for a simple application, it should be below 
500 milliseconds. 

§£HEB._IC_1ST_D1I^SCHED: The average elapsed time between the 
scheduling of the MEP/EKE and its first EL/I call. Typically, the major 
contributing factor in this is program lead time. Typically, this value 
should be between 200 and 5CC milliseconds. Basic steps to improve this 
figure are: 

• Maintain a compact (compressed) IMSVS.PGMLIE containing only the 
MEPs used by the online system. 

• Specify this IMSVS. EGKIIB as the first step/job library in the MPP 
region JCL. 

• Use the COBOL options of NOEES, NODYNAM and NCENEJCE. 

VLhl SEp_TIME^TJANS : Same as EIAESEE TIME/SCHEC, but now per 
transaction. If TBAN.EEQ./SCH. is 1, they are the same. 

EL^I_Call_Summarjj iL _Pag6S_JS x _2C 

This report gives a sumnary cf the number of DL/I calls per ESB (that 
is, program) , per segment returned, and the number of IWAITs for these 
calls. For a discussion refer to the DL/I Call Summary Report section 
of the DB Monitor in the first part of this chapter. 
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ESS £E2£iit» 5§9§ 22 

This report gives a compact, over-all picture of IMS/VS performance 
during the period of the DC monitor trace interval. The headings and 
contents of this report are self-explanatory. Definitions of terms used 
are included in the discussion of previous reports. 

0SING_TBI_VTiM_S10K£GE_P0QL_lBASE 

This section describes how to use the VTAM storage pool trace to 
optimize the VTAM main storage pool in your installation. 

This VTAM trace facility is dependent upon the OS/VS 

General Trace Facility (GTF). 

The VTAM storage pool trace records the usage of all VTAM storage pools. 
When both GIF (USR trace cpticn) and VTAM storage pool trace are active, 
the storage pool trace infcriaticn is collected on every 1000th VTAM 
reguest to obtain a storage pool element. 

The VTAM storage pool trace collects the following information for each 
of the VTAM storage peels: 

Storage pool name 

The maximum number of elements allocated from the pool at any one 
time since the last trace record was written 

The maximum number of queued requests for buffers at any one time 
since the last trace record was written 

Number of currently unallocated elements in the pool 

Date and time, if TIHE=YES was specified in the GTF START command 

OPERATING THE TRACE 

To be able to activate the VTAM storage pool trace, GTF must be started 
first. If you are using cur sample cataloged procedure VTAMGTF as 
generated by job //SAMPI56 in IMSVS.PRIMEJCB, you should use the 
fcllcwing procedure- 

Starting_the_Trace 

erter: £ VTAMGTF. P1 (This starts GTF) 

response: nn HHI100A SPECIFY TRACE OPTICNS 

enter: nn,TRACE=RNIO,USR 

response: mm HHL125 RESPECIFY TRACE CPTICN CR REPIY 

enter: sm,0 

enter: F P0, TRACE, TYPE=SKS,IE=VTAMBUF 

This starts the VTAM storage peel trace 

Note: In the above it is presumed that VTAM runs in P0 and GTF in P1. 
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StC]3]3in<i_the_Trace 

enter: F PO,NCTBACE,TYEE=SBS,ID=VTAMEUf 

enter: P VTAMGIF-F1 

Ili^tiBS ££§ l£§5€ Output 

Job //SAMEU96 in IMSVS. FFIMEJCE can be used to print the VTAM trace 
output. 

OPTIMIZING VTAM STOBAGE POOI PAEAMETEHS 

VTAM has eleven storage pools to control the buffering of data. VTAM 
dynamically allocates and deallocates space in these pools fcr the VIAM 
control blocks, I/O buffers, and channel programs that control the 
transmission of this data. 

The basic procedure for tailoring the VTAM storage pool values is to 
initially operate VTAM using the worst-case storage pool values as 
described in CS/VS Storage Estimates. Then adjust the storage pool 
values by using the VTAM storage pool trace facility. To tailor the 
VTAM storage pools, determine the following values for each VTAM storage 
pool: 

• bno, the maximum number of elements in the pool 

• bth, a threshold number of elements for a pool 

• bsz, the size of each element (in bytes) in a pool (specify for 
IOEUf and PPBUF only) 

Storafle_Pool_JSMSl._Trac€_D€scription 

The VTAM storage peel (SMS) trace records information on the use and 
availability of VTAM»s buffer pools. The trace records are written at 
regular intervals, after every 1,000 reguests for buffers. Each set of 
records contains the maximus number of buffers in use, the maximum 
number of reguests for buffers gueued, and the current number of 
available buffers for each cf VTAM's eleven buffer pools. An example of 
VTAM storage pool trace output is shown in Figure 9-3. 

*** DATE DAY 080 YEAR 1978 TIME 20.56.20.407148 

USRFD FF0 VTAM BUFFERS MAXU MAXQ AVNO MAXU MAXQ AVNO MAXU MAXQ AVNO MAXU MAXQ AVNO 

10 0023 0000 0CB2 PP 0002 0000 002C UP 000E 0000 0024 WP 0003 0000 0011 

NP 0007 0000 0025 LF 0008 0000 002A CR 0006 0000 0037 UE 0002 0000 002C 

SF 0001 0000 001A SP 0000 0000 0005 AP 0005 0000 0028 
TIME 75380.399270 

Figure 9-3. Sample VTAfl Trace Output 

Legend: 

POCIID 

Identifies which buffer pool the trace entry is for. Pool IDs are: 

10 Fixed I/O pool (IOBDF) 

PP Pageable I/O peel (PPB0F) 
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LP Large pageable pool (LPBOF) 

WF Working set pageatle peel |«PBDF) 

NP Ncnworking set pageatle cccl (NPBUF) 

LF Large Fixed pool (IFEUF) 

CR Copy EPL pool JCBEIEUF) 

UE UECB pool (UECBUF) 

SF Small fixed pool JSFBUF) 

SP Small pageatle pool (SPBUF) 

AP ACE cccl (APEUI) 

MAXU 

Indicates the maximum number of buffers in the pool that were in use 
at any one time in the last interval, A MAXU value of 0, however, 
does not mean that all buffers in the pool were released, tut that 
there were no additional requests for buffers during this interval. 

MAXC 

Indicates the maximum number of requests for buffers that were 
queued at any one time since the last interval. 

AVNO 

Indicates the average number of buffers in the pool that were 
availahl€ during the interval. 

iJjustin3_.th€_VTAM_Stoiaaj§_Pccls 

Eased on a VTAM trace output of several hours of regular production, use 
the following guidelines in adjusting the VTAM storage pool parameters 
as specified in jet //SAMPI5U. 

For every pool find the following values: 

• Average of all HAXUs related to pool 

• Average of all MAXCs related to pool 

• Average of all AVNOs related tc pool 

• Highest MAXD related tc peel 

• MAXQ related to highest MAXD 

• AVNC related to highest KAXU 
Decrease bth and bno if: 

• highest MAXU is always at least 10% lewer than bth. 
Increase bth and tno if: 

• Average and/or highest MAXU value is larger than or equal to bth. 

• Average and/or highest KAXU value is close to bth and average and/or 
highest AVNO is clcse tc zero. 
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Notes : 

1. The increase should fce at least as high as the highest BAXC value. 

2. The relationship between hth (threshold value) and bno (number of 
buffers inpool) is described in OS^VS System Programming Library. 

(MVS).: Storage Estimates, GC28-0604. 

^TA^CCMMONICiTION.EISIGN^OgTIMIZATIQN 

The importance of a good data base and program design for the 
performance of an IMS/VS online system is even more apparent than for a 
batch system. The guidelines for data base design and DL/I call used by 
programs, as given in the first part of this chapter, still fully apply. 

Another important factor of general interest in data communicaticn 
design is the transaction response time. 

As discussed in the section "Transaction Response Time Considerations" 
of Chapter 3, "Data Communication Design," the response time consists of 
two components: 

1. Network response time. 

2. IMS/VS response time. 

NETWGBK EESPONSE TIME FACTOBS 

The following parameters influence the network response time: 

Length of input data character stream 

Length of output data stream 

Line mode operation, that is, half or full duplex 

Line speed and lire length 

Modem turnaround time 

Number of clusters and number of terminals per cluster 

Communication controller delay time 

Number of transactions per terminal, arrival rate, and distribution 

Eased on the above factors, an assessment can be made for the network 
response time. 

IMS/VS EESPONSE TIME FACTCBS 

One of the most important factors which influence the performance of an 
online IMS/VS system is the MPP service time. 

The MPP service time is the elapsed time between scheduling of the 
transaction and the completion of its processing by the MPP. 
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The basic components of the BFE service time are: 
1- Program loading of the Efl- 

2. Betrieval of input nessage and associated physical I/Cs. 

3. Data base calls and associated I/Os. 
U. Application program processing time. 

5. Insert of output message into the message queue and its associated 
physical I/Os (if no free queue buffer is available) . 

6. CS/VS paging during any cf the above activities. 

The twc mcst important components from the above list are usually the 
program load time and the data base calls with their associated I/Os. 
Typically, prograi lead tine is between 200 and 500 milliseconds elapsed 
time, and a direct I/C is between 30 and 50 milliseconds elapsed time, 
assuming 3330 disk drives. 

Note: IMS/VS provides for prelcading of selected application programs 
and PL/I modules. This preload option is not included in our subset, 
but you might consider its use as the next step on improving systems 
performance. More infcriaticr en the prelcad option is included in 
Chapter 2 of the IMS/VS Installation Guide under the topics "Making 
High-Use Program Modules resident" and "Organizing PL/I Modules for Use 
with the PL/I Optimizer." 

Sample_IMS/VS_ResiOjQS€_Tiff€_Estimate 

We will now discuss a very simple IMS/VS response time estimation, based 
solely on MPE service time considerations. 

Assumptions: 

Lightly loaded system, that is, ample available CPU time for IMS/VS 
activities. 

One MPP region. 

All MEEs have roughly same service time. 

MPP is loaded for each transaction; program load time is 300 
milliseconds. 

Average of K DL/I calls with average of 1 I/O per DI/I call of HO 
milliseconds average elapsed time. 

The message inter-arrival time is 2 seconds {one message every 2 
seconds) with an exponential distribution. 

Basic gueueing theory is applicable. 



Optimization 9-31 



E s t i ma te s : 

Eased on above assuipticns, the following parameters can be 
derived/calculated : 

MPE Service Tine: TS = 300*10*40=700 milliseconds, 

Arrival Rate: A = 0.5 messages/second 

MPF Utilization: = 1S*A=C35 

WPP Wait Time: TW = U*TS/ ( 1-U) =380 milliseconds 

MPF Response Time: TR = !S«-Tfi=1.C8 seconds 



Where : 

• The MPP vait tioe is the average time a message must wait in the 
queue before the HFE region can process it. 

• Ihe MPF response time is the average interval response time of a 
transaction, that is, the time between the enqueue of the input 
message in the queue and the enqueue of the output message in the 
queue. 

Note j : 

1. The formula for TV normally applies only for utilizations below 60S 
(0<0.6) . 

2. Many other factors can influence the total IMS/VS response time, 
such as: 

Loading of DBDs, PSBs and MID/MCDs, DIF/DOFs. 

Data base open processing (required after D8D (re) lead) • 

CPU, channel, and disk drive utilizations. 

Eispatching priority of CTL and MPP regions. 

Location of IMS/VS system data sets, noticeably the queue, 
fcrmat, and program library data sets. 
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APIJKIX £• IflS/VS STA30S CODES QOJCK BEFEFJJNCI 



STATUS 
CODE 


DATA BASE CALLS 


MSG CALLS 


SYSTEM CALLS 


CALL STATUS 


DESCRIPTION 


GU 
GHU 


GN 
GHN 


DLET 
REPL 


ISRT 
ILOADI 


ISRT 

(ADDI 


GU 


GN 


ISRT 


CHNG 


CHKP 


XRST 


CALL 
COMPLETED 


ERROR 

IN CALL 


I/O OR 
SYST ERROR 


AE 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 






X 




SEGMENT I'O AREA REQUIRED. NONE SPECIFIED IN CALL 


AC 


X 


X 




X 


X 
















X 




HIERARCHICAL ERROR IN SSAs 


AD 


X 


X 








X 














X 




INVALID FUNCTION PARAMETER 


AH 


X 


* 




X 


X 
















X 




CALL REOUIRES SSAs NONE PROVIDED 


Al 


X 


X 


X 


X 


X 


















X 


DATA MANAGEMENT OPEN ERROR 


AJ 


X 


X 




X 


X 
















X 




INVALID SSA QUALIFICATION FORMAT 


AK 


X 


X 




X 


X 
















X 




INVALID FIELD NAME IN CALL 


AL 


X 


X 


X 


X 


X 
















X 




CALL USING LT PCB IN BATCH PGM 


AM 


X 


X 


X 


X 


X 
















X 




CALL FUNCTION NOT COMPATIVLE W/PROCESSING 
OPTION OR SGMT SENSITIVITY 


AO 


X 


X 


X 


X 


X 


















/ x 


I/O ERROR OSAM. BSAM. OR VSAM 


AP 












X 


X, 


x 


X 


x 






X 




MORE THAN 4 CALL PARAMETERS INVALID FOR DC PCB 


AT 






X 


X 


X 






X 










X 


X 


USER 10 AREA TOO LONG 


AV 
















X 










X 




RESPONSE ALTERNATE PCB REFERENCED BY ISRT CALL 
HAS MORE THAN ONE PHYSICAL TERMINAL ASSIGNED FOR 
INPUT PURPOSES. NOTIFY MASTER TERMINAL 


Al 


















X 








x 




CALL ATTEMPTED WITH 8 CHAR LOGICAL TERMINAL 
NAME NOT KNOWN TO SYSTEM 


A2 


















X 








X 




CHANGE ATTEMPTED WITH INVALID PCB 


A3 
















X 










X 




INSERT ATTEMPTED TO A MOD TP PCB WITH NO DESTINATION 
SET 


A5 
















X 










x 




FORMAT NAME SPECIFIED ON 2ND OR SUBSEQUENT MSG 
ISRT CALL 


A6 
















X 










X 




OUTPUT SEGMENT SIZE LIMIT EXCEEDED ON ISRT CALL 


A7 
















X 










X 




NUMBER OF OUTPUT SEGMENTS INSERTED EXCEEDED THE 
LIMIT BY ONE 


DA 






X 




















X 




SEGMENT KEY FIELD HAS BEEN CHANGED 


DJ 






X 




















X 




NO PRECEOING SUCCESSFUL GET HOLD CALL 


DX 






X 




















X 




VIOLATED DELETE RULE 


GA 




X 




















X 






CROSSED HIERARCHICAL BOUNDARY INTO HIGHER 
LEVEL {RETURNED ON UNQUALIFIED CALLS ONLYI 


GB 




X 


























END OF DATA SET, LAST SEGMENT REACHED 


GE 


X 


X 






X 




















SEGMENT NOT FOUND 


GK 




x 




















X 






DIFFERENT SEGMENT TYPE AT SAME LEVEL RETURNED 
IRETURNED ON UNQUALIFIED CALLS ONLY I 


II 










X 




















SEGMENT TO INSERT ALREADY EXISTS IN DATA BASE 


IX 










X 
















X 




VIOLATED INSERT RULE 


LB 








x 






















SEGMENT TO INSERT ALREADY EXISTS IN DATA BASE 


LC 








X 






















KEY FIELD OF SEGMENTS OUT OF SEQUENCE 


LD 








X 






















NO PARENT FOR THIS SEGMENT HAS BEEN LOADED 


LE 








X 






















SEOUENCE OF SIBLING SEGMENTS NOT THF SAME AS 
DBDSEOUENCE 


NE 






x 






















x 


DL 1 CALL ISSUED BY INDEX MAINTENANCE CANNOT FIND 
SEGMENT 


NO 






X 


X 


X 


















X 


10 ERROR OSAM, BSAM OR VSAM 


QC 












X 








X 










NO MORE INPUT MESSAGES 


QD 














X 
















NO MORE SEGMENTS FOR THIS MESSAGE 


QE 














X 












X 




GET NEXT REOUEST BEFORE GET UNIQUE 


OF 
















X 




x 






X 




SEGMENT LESS THAN FIVE CHARACTERS ISEG LENGTH 
IS MSG TEXT LENGTH PLUS FOUR CONTROL CHARACTERS! 


OH 
















X 










X 




TERMINAL SYMBOLIC ERROR OUTPUT DESIGNATION UNKNOWN 
TO IMS/VS ILOGICAL TERMINALS OR TRANC0DE1 


RX 






X 




















X 




VIOLATED REPLACE RULE 


X3 
















X 










X 




INVALID SPA 


X7 
















X 










x 




LENGTH OF SPA IS INCORRECT IUSER MODIFIED FIRST 
SIX BYTES! 


XC 
















x 










X 




PGM INSERTED MSG WITH Z1 FLD BITS 
SET RESERVED FOR SYSTEM USE 


XD 




















X 




X 






IMS IS TERMINATING FURTHER DL/I CALLS MUST NOT BE 
ISSUED NO MESSAGE RETURNED 
INTERNAL GSAM ERROR 


XX 


X 


X 




X 


X 






1 1 1 






X 


bb 


X 


X 


x 


x 


X 


x 


X 


X 1 X I X I X 


X 






GOOD NO STATUS CODE RETURNED, PROCEED 


NOTE bb indicated blanks 
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!H1»DIX B, IMS/VS STAIOS CODES ANE POSSIBLE CAUSES 



The following listing of IMS/VS status codes and possible causes is 
divided intc two parts. The first part lists the status codes which 
are, in general, caused by application prcgram errors. The second part 
lists the status codes which are, in general, caused by system errors. 

U2i£S * more detailed discussion of these and other status codes can be 
found in Appendix E of the IMS/VS. Application Programming; £efer.ence 
Manual, 

ifUJClICN PPQGP|» JPECE STATUS CODES 

The following status codes are the most common ones caused by 
application prcgram errcrs (errcr in call) in our subset. 

AB: Segment I/O area is reguired but was net specified in the call. 

AC: SSA (s) contains an errcr in hierarchical seguence. 
Possible causes: 

1. No segment name equal to that specified in SSA found within 
sccpe of this FCE- 

2. Level at which this SSA appears is out of sequence with that 
specified bj the PCB . 

3. Twc segments of the same level are specified in the same call. 

AD: An invalid function parameter was supplied. 
Possible causes: 
1.. Invalid function string 

2. A GO or GN was requested for a terminal ECB other than the 
I/C PCE- 

3. Invalid request type to a DC-PBC. 

4. A call has been issued tc the message queues with a EE-FCE. 

AH: No SSA (s) was specified in call. Call required at least one SSA, 
and none was specified. 

AJ: SSA qualification format was invalid. 
Possible causes: 
1.. Invalid comtand cedes. 

2. Invalid relational operators. 

3. Missing right parenthesis of Boolean connector. 

IMS/VS Status Codes and Possible Causes £. 1 



4. DLET call has nultiple SSAs or qualified SSAs. 
5- EEPL call has qualified SSAs. 

6. ISRT call has the last SSA qualified. 

7. A path insect call into an existing data base involves a 
logical child segment. 

AK: An invalid field name was supplied in the call. 
Possible causes: 

1. Unable to find the specified field name. 

2. When accessing a logical child, a field name from the othe 
(paired) logical child is used for the destination parent 
concatenated key pcrticn. 

AL: The call is using a terminal PCB in a DL/I program. 

AM: Call function not compatible with processing option, segment 
sensitivity, or transaction-code definition. 

Possible causes: 

1. Command cede D used fcr path retrieval call without path 
sensitivity 

2. Processing option cf t and call function is not insert 

3. DLET, REPL, cr ISRT call without corresponding segment 
sensitivity 

4. A DIET, EEPL, or ISPT call was issued by a program while a 
transacticn defined as inquiry was being processed. 

A GET call was attempted for a segment with KEY sensitivity. 
Correct the error by specifying DATA sensitivity. 

5. This status cede cccurs for a checkpoint (not restart) call if 
a GSAM/VSAM data set is opened for output. 

6. An invalid request was included in a GSAM call. 

7. Any call to a GSAK dummy data set is invalid. 

AT: Errcr in call. The length of the user's I/O area data is greater 
than the area reserved fcr it in the control region. The length 
cf the area reserved was determined by the AC6 utility program, 
DESOACBO, and printed as part of its output. 

Action: Correct the PSB cr the program (message segment length 
field) in ecrcc. 

AY: Insert call ignored because the logical terminal referenced by the 
response alternate PCB currently has more than one physical 
terminal assigned to it for input purposes. 
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Action: Ask the master terminal operator to determine (use 
/EISPLAX ASSIGNMENT ITEBK X) which physical terminals (2 cr more) 
refer to this logical terminal. Dse the /ASSIGN command to 
correct the problem. 

A1: The CHNG call was attempted with an eight -character logical 
terminal name which «as unknown to the system. 

A£ii£J3* Correct program. 

A2: The CHNG call was attempted with an invalid PCE. It was either 
net an alternate PCB, was not defined as modifiable, or had a 
message in process but incomplete. 

l£ii2S : Correct program. 

A3: An INSEET call was attempted to a modifiable alternate PCE which 
had no destination set. 

Action: Issue a CHNG call tc set the PCE destination, and reissue 
the~INSIBT call. 

A5 An invalid call list was supplied. A fourth parameter (HOD name) 
was supplied, but the function was not ISRT for the first segment 
cf an cutput message. 

Action.: Correct the IS6T call and retry the application program. 

A6: Insert call ignored because output segment exceeded specified 
limit. 

A£ii£S : Correct the application program. 

A7: Insert call ignored because number of output message segments 

inserted exceeded specified limit by one. If another attempt is 
made to insert too many segments before the program issued another 
GU, the program is afcended. 

A£ii£D : Correct the application program. 

EA: A segment sequence field has been changed; no action in data base. 

DJ: No previous successful get hold call; no action in data fcase. 

DX: Violated delete rule; tried to delete across a logical 
relationship. Check BOLES = parameter on DBD. 

GA: Call is completed. 

IiLE2§Ll& tion : Crossed hierarchical boundary into higher level. 
This status code is returned on unqualified calls only. 

Action: User determined. 
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GB: Call is not completed. 

Explanation: This is the end of the data set; last segment is 
reached. If GSAH, the data set will have been closed. 

Action: User determined. 

GE: Call is not completed. 

Ii£iJiJ3iifiJ55 Segment has not been found. 
Action: User detenined. 

GK: Call is completed. 

ISBJLSUJiiSJS* Different segment type at same level returned. This 
status code is returned on unqualified calls only. 

Action: User determined. 

II: Call is net completed. 

IiEl3£ati2£2 The segment that the user tried to insert already 
exists in the data base. 

Possible causes: 

1- Segment with egual physical twin seguence field already exists 
for parent. 

2. Segment with equal logical twin sequence already exists for 
parent. 

3. Logical parent has logical child pointer, logical child dees 
not have logical twin pointer, and segment being inserted is 
second logical child for logical parent. 

4. Segment type dees not have physical twin forward pointer, and 
segment being inserted is second segment of this type for 
parent or is second HCAH root for one anchor point. 

5. The segment being inserted is in an inverted structure; that 
is, the iamediate parent of this segment in the logical 
structure is actually its physical child in the physical 
structure. 

Action: User determined. 

IX: Violated insert rule. 
Possible causes: 

1. Insert of logical child and logical or physical parent does 
not exist, or wrong EECK. 

2. Insert of logical cr physical parent via its logical path. 

3. ISRT reguest after previous Open, Close or I/C error status 
code . 
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4- A GSAH ISB1 call was issued after a previous AI or AC status 
code was returned. 

l£tiQB s Correct program. 

LB: Call is not completed. 

5l£i§£§$i2S : The segment user tried to load already exists in the 
data base. 

Possible causes are: 

1. A segment with an equal physical-twin-seguence field already 
exists for the parent- 

2- A segment type dees not have a physical-twin-forward pointer 
(PTR=NS in SIGM statement in DBD) and the segment being 
inserted is either the second segment of this segment type for 
the parent or the secend HD&M root for cne anchor point. 

3. An application program inserted a key of X'FF'-.FF 1 into a 
SHISAK or HIEAM data base. 

iSiiSS 2 User determined. 

LC: Call is net completed. 

ExEi§S§ii2D : Ke Y field of segments is out of seguence. 
Action: Check and correct. 

ID: Call is not completed. 

Explanation: No parent has been loaded for this segment. 
Actios : Check and correct. 

LE: Call is not completed. 

Si£l§natign: Sequence of sibling segments is not the same as the 
sequence in tee £ED. 

Action: Check and correct. 

Kft: Call is not completed. 

l£J:l§£ a .$i2!} : Index maintenance issued a DL/I call, and the 
segment has not been fcucd. 

i£.£ipji: User deter lined. 

QC: Ihere are no more input messages. If CHRP call, call was 
successful. 

Action: The program should terminate. 
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QD: There are no more segments for this message. 
i£*i25 : As appropriate, 

QE: A GET NEXT call was issued before a GET UNIQUE. 
Action: Check and correct, 

QF: Length of segment is less than five characters. Allowable segment 
length is length of message text plus four control characters.) 

IStiSfis Check and correct- 

QH: The output designation, the LTERM, is unknown to IMS/VS. 

iSi!2S : Check LTERM name specification in PCB or CHNG call. 

FX: Violated replace rule. Review the RULES= parameter in the EEEs. 
Action: Correct program/EED. 

X3: Invalid SPA (user modified the first six bytes). 
Action: Correct the program. 

X7: The length of the SPA is incorrect (user -modified first six 
bytes) . 

i££i2E : Correct the program. 

XC: Program has inserted a message which has some Z1 field bits set 
which are reserved for IMS/VS use. 

Action: Correct the program to prevent it from setting those 
bits. 

XD: IMS/VS is terminating by a CHECKPOINT FREEZE or DUMPQ. This code 
is returned only frcm a CHRP call issued by a batch-message 
application program. The checkpoint itself was successful. 

Action: Any subsequent EI/I call will result in an abend. The 
EMP should terminate. 

§IS1EM ERBCR S1AT0S CCEES 

The following status codes represent the most common errors in our 
subset : 

AI: I/O, system, or user error 

£.£El§.B a Jtion: Data management open error. 
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Possible causes: 

1. Error in DD cards. 

2. The data set vas opened for something other than load mode, 
but it is not loaded. 

3. Buffer too snail to hold record read at open time. See 
Chapter 7 fcr miriiui buffer peel size. 

4. DD cards for logically related data bases not supplied. 

5. For an CSAM data set, the ESCBG field of the OSAB DCB, DSCB, 
or JFCE does net specify PS or DA. 

6. For an old OSAM data set, the BOFI or BLKSIZE field in the 
DSCE is zero. 

7. The data set is being opened for load, and the processing 
option for cne or irere segments in other than I or LS. 

8. The allocation of the OSAM data set is invalid; allocation is 
probably (1,,1) rather than (1,1), and this causes the DSOBG 
to be PO. 

9. Processing options is L, the OSAB data set is old, and the 
DSCE LEECl and/or EIKSIZE does not match the EBD LBECL and/or 
ELKSIZE. 

10. Incorrect or missirg information prevented computation of 
blccksize or the determination of the logical record length. 

11. A catalog was not available for accessing a VSAK data base 
that vas requested. 

12. OS/VS could not perform an OPEN, but the I/O reguest is valid. 
Information is either missing, or data definition information 
is incorrect. 

A ct ion: Check DD cards; ensure ddname is name specified on 
DATASET card of EBD. Segment name area in PCB has ddname of data 
set which could not be opened. 

AO: There is a physical I/C error. When issued from GSAM, this status 
code means that the error cccurred when: 

1. A data set was accessed, or 

2. She CLCSE SXNAE routine was entered. The error occurred when 
the last blcck or records was written prior to closing of the 
data set. 

l£lsi28 : Eetermine whether the error cccurred during input or 
output, and correct the prcblem. Beccver the data set. 

NO: I/C error 

l5Ei§fii£i2S : There was a BSAM, VSAM, or OSAM physical I/O error 
during a EL/I call issued by indexing maintenance. 

Action: Check and correct (recover data base). 
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IX After initialization, the XX status code indicates an IMS/VS 
errcr--Frobably GSAM. 

An XX status code from initialization itself (prior tc the first 
DL/I call) aay be either a system, IMS/VS, or user error. 

l5Bl§S3ti2S : When the XX status code is issued froa 
initialization, the cause may be: 

Insufficient storage 
Invalid CED 
Invalid blocksize 
Invalid option 
GSAK error 

i££i°.£ : Any subsequent GSAH call will result in an abend. The 
application should terminate. 
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DLIBATCH procedure 7.68 
overview 1.16 
system flow 1. 16 
BMP (§ee batch message program) 
buffer "poo Is, IMS/VS 
data base 

description 7.59 
performance considerations 9.12 
specification of 7.61 
statistics 9.1, 9.7 
online 

description 7.23, 7.59 
performance considerations 9. 14 
specification of 7.23, 7.61 
statistics 9. 14 
buffer services, IMS/VS DL/I, 
control statements for 
OSAM buffer pool 7.62 
VSAM buffer pool 7.61 
B0FPOOLS macro statement, IMS/VS system 
definition 7.23 



calls, DL/I batch 

checkpoint (CHKP) 4.44 
command codes, ulrecl 4.21 
data base positioning 

after 4.23 
definition 1.14 
delete (DLET) call 4.19 
description, general 4.7 
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forward movement 4.13, 4. 15 
function code 4.8 
get calls 

get next (Gtf) 4. 15 
get unique (GU) 4. 14 
hold forms 4. 18 
insert calls (ISRT) 4.20 
overview 2.9 
gualified 4.16 
replace (REPL) 4.18 
restart (XRST), extended 4.81 
segment search argument (SSA) 
characteristics of 4.11 
command codes for 4. 11 
concept and function 4.9 
qualification of 4.10 
structure 4.9 
calls, DL/I online 

change destination (CHNG) 4.54 
message insert {ISRT) 4.53 
message retrieve (GO, GN) 4.52 
scratch pad area (SPA) insert 4.66 
scratch pad area (SPA) retrieve 4.66 
calls, IMS/VS system service 
checkpoint (CHRP) 4.4 1 
restart (XRST) 4.42 
statistics (STAT) 4.25 
cataloged procedures (see IMS/VS 

cataloged procedures) 
change accumulation utility (see data 

base change accumulation utility) 
chained control block linkage, MPS 3.20 
chaining MIDs and MODs 3. 20 
NXT= operands 3.32, 3.33 
checkpoint call (see, CHRP call) 
checkpoint/restart 
batch 4.41 

description 3.15 , 4.41 
extended 4.41 

frequency of checkpoint 4.4 1 
GSAM, with 4.45 
introduction 
batch 1. 15 
online 1.31 
online 3.15, 4.47 
use of 4.41 
CHKP call (data base) 4.44 
CHNG call (data communication) 4.54 
clear key, 3270, impact of 3.41 
COBOL, conventions and use of 
batch program structure 

call formats (see individual calls) 
guidelines 4.32 
IMS/VS interface 4.4-4.11 
online program structure 

call formats (see individual calls) 
conversational MPP 4.68 
guidelines 4.60, 4.68 
IMS/VS interface 4.50 
inquiry MPP 4.60 
COMM macro statement, IMS/VS system 
definition 

BTAM, when using 7.31 
VTAM, when using 7.27 



command language, IMS/VS terminal 1.29 
commands, IMS/VS 

description (see IMS/VS Primer 
Master Terminal Operator's Guide) 

protection against 
unauthorized use 7.65 

subset. Primer 1.38 
communications network 

defining, IMS/VS 7.27, 7.31 

defining, NCP/VS 7.38 

defining, VTAM 7.38 

introduction 1.24 

Primer sample 7.44 
compilation statements, MFS 3.44 
concatenated keys 2.8 
concatenated segments, logical 

relationship 2.19, 2.24 
configurations, sample network 7.44 
contention for resources, message 
scheduling effects of 3.9, 3.12 
control block pools 

definition 7. 23 

optimization 9.14 
control blocks, MFS 

(see also DIF, DOF, MID, and MOD) 

compilation 3.34 

creation 3.34 

linkages 3. 20 

relationships between 3.20 

summary 3.18 
control region, IMS/VS 

description 3.4 

system flow 1.32 

structure 3.4 
control structure, DB system 1.16 
conventions, naming 1. 18 
conversational processing 

definition 1.29 

description 3. 14 

design considerations 3.57, 3.63 

interactive processing, 
relation to, use for 3.56, 3.61 

program structure for 4.64 

scratch pad areas (SPAs), 
use of 4.64 

scratch pad area layout 4.65 

system definition of 7.23, 7.26 

termination, how 4.67 
converting from batch to online 7.78 
copy function, 3270 3.18, 7.30, 7.35 
corequisite publications p. 5 
count parameter (DO statement) 

DFLDs 3.41 

MFLDs 3.3 4 
crossing a logical relationship 2.21 
CTLUNIT macro statement, IMS/VS system 

definition 7.32 
cursor attribute 

C0RS0R= operand (DPAGE statement) 3.41 
cursor positioning 

default 3.41 

program, by 4.57 
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data base (see also data base design) 
concepts 1.6-1-13 
content 

fields 2.7 
pointers 2. 14 
segments 2. 7 
records 2.6 
free space 2.13, 2.33 
anchor points 2;11, 2-31 
defining 2.29 
GSAM, using 2. 16 
HDAM, using 2.11 
HIDAM , using 2. 17 
index, primary 2-17 
index, secondary 2.25 
introduction 1.1 
logical (see logical data base) 
organization types 2-5 
physical (see physical data base) 
position after a call 4. 23 
sequence fields and access paths 1-9 
simple HISAM, (SHISAM) 2.15 
space allocation for 2.83-2.85 
data base access methods 
introduction 2.5, 2.10 
performance considerations 2.80, 9.30 
when used 2.78 
data base administration 1.17 
data base backout utility 

(DFSBBO00) 6. 14 
data base buffering 

defining pool sizes 7.61 
overview 7.61 
data base change accumulation utility 

(DFSUCUMO) 6.9 
data base description block (DBD) 
purpose of 1.14 

requirements, definition of 2-29 
Data Base Description Generation (DBDGEN) 
definition of 1.14 
execution of 2-29 
procedure used for 7.68 
data base design 
checklist 9. 11 

concepts and methodology 2.62 
intermediate data base, of 3-64 
introduction to 2.64 
online considerations 3.63 
optimization 9.12 
performance checklist 9.11 
structure rules 
basic 1.7 

logical relationship, with 1. 10 
secondary indexing, with 1-12 
structure changes, rules for 5.27 
transaction/data element 

matrix, use of 2.67 
tuning 9.12 
data base dump (see data base image 

copy) 
data base image copy 6.2, 6.7 
data base image copy utility 

(DFSUDMPO) 6.7 
data base input/output interface 
(see Data Language/I (DL/I) ) 



data base integrity 1.15, 1.30 
data base load, initial 
basic data base 4.26 

logical related data bases 4.38, 5.23 
secondary index data base 4.41, 5.25 
data base logical relationships 
concepts 1-10 
description 2.17 
defining 2.43 
data base logical relationship resolution 
utility programs 

initially loading a data base 
containing logical 
relationships 5.23 
overview 5.13 
prefix resolution utility 

(DFSURG10) 5.15 
prefix update utility 

(DFSURGP0) 5.19 
prereorganization utility 

(DFSURPR0) 5.13 
reorganizing a data base containing 

logical relationships 5.26 
secondary indexes, 
building 4.41, 5.25, 5.27 
data base logging capability 1-15, 1.30 

(§§§ §.i§o log, IMS/VS system) 
data base monitor (see DB Monitor) 
data base organization, types of 2.5 
data base prefix resolution utility 

(DFSURG10) 5.15 
data base prefix update utility 

(DFSURGP0) 5.19 
data base prereorganization utility 

(DFSURPR0) 5.13 
data base processing intent, message 
scheduling 

conflicts, how resolved 3. 12 
scheduling, impact upon 3. 10 
data base record 1.6, 2.6 
data base recovery 
basic 6.2 
full DL/I 6.4 
introduction 6.1 

log tape, IMS/VS, significance 6.5 
procedures for 6-20 
data base recovery utility 

(DFSURDB0) 6-12 
data base reorganization 
flowchart 5.24 
introduction 5-1 
performance considerations 5.25 
structural changes, making 5.27 
symptoms for 5.22 
utilities for 5.3 
data base reorganization/load 
processing 
(see data base reorganization) 
data base secondary indexing 
concept 1. 12 
defining 2.50 
description 2.25 
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data base structure rules 
basic 1.7 

logical relationships 1.10 
secondary indexing 1. 12 
data base system 

access methods 2.5 
application program, 

relation to 1. 16, U. 1 
control sequence flow 1.16 
facilities provide with 1.5 
performance, monitoring 9. 1 
GSAM 2. 16 
HDAM 2.11 
HIDAM 2.11 

installation of 7.10, 7.138 
logging 6.5 
monitor, DB 9.3 
operating environment, batch 

scheduling 1. 16 
OS/VS considerations 7.2, 7.78 
OSAM 2.10 

planning for installation 1.21 
STAE/ESTAE, use of 6.5 
system definition, IMS/VS 7.5 
utility programs 1. 15 
data base system flow 1. 16 
data base/data communications (DB/DC) 
system 

introduction 1.26 
facilities 3.6 

relationship -to DB system 3.6 
system flow 1.32 
data communication 

basic concepts 1.21 
features, IMS/VS 1. 26 
system flow, IMS/VS 1.32 
system network architecture, 
basic concepts 1.24 
data communication macro statements, 
IMS/VS system definition 
ETAM macro set 
COMM 7.31 
CTLONIT 7.32 
LINE 7.32 
LINEGEP 7.31 
NAME 7.35 
TERMINAL 7.33 
VTAM macro set 
COMM 7.27 
NAME 7.30 
TERMINAL 7.29 
TYPE 7.28 
data independence 1.6 
Data Language/I (DL/I) 

call requests, functions performed 
input/output class 
data base 4.7 
message 4.52 
language interface 1.14 
data, limiting access to 1.14 
data manipulation language 1.14 
data security 
bat ch 1.15 
online 1.29 
extended 1.29 



data sets, IMS/VS, allocating and 

catalogging 7.9, 7.41 
data spaces, defining VSAM, for 

data bases 2. 85 
data structure, application 1.6, 2.74 
data structures, IMS/VS 1.7, 2.77 
data structure, changing the 5.27 
data structure, secondary indexes 1.12 
DATABASE macro statement, IMS/VS 

system definition 7.24 
DATASET statement 

basic data base, for 2.33 
GSAH data base, for 2.42 
logical data base, for 2.48 
secondary index data base, for 2. 54 
DB monitor 

description 9.3 

output interpretation and 

sample 9.7 
report print program 
(DFS0TR30) 9.5 
DB PCB 

defining a 2.57 
description 1.14 
programs view of 4.5 
DBA (see data base administration) 
DBD (see data base description block) 
DBD statement 

basic data base, for 2.31 
GSAM data base, for 2.42 
logical data base, for 2.47 
secondary index data base, for 2.54 
DBDGEN statement 2.39, 2.42 
(§.ee also data base description 
generation) 
DC monitor 

description 9.21 

output interpretation and 

sample 9.23 
report print program 
(DFSUTR20) 9.22 
DC PCB 

defining a 3.49 
description 3.11 
program view of 4.49 
default attributes, MFS 3.35 
defining IMS/VS batch system 7.5 
defining IMS/VS online system 7.13 
defining NCP/VS 7.39 
defining physical data bases 
basic 2.29 

logical relationships, with 2.43 
secondary indexes, with 2.50 
defining VTAM 7. 38 
definition statements, MFS 
device format 
DEV 3.39 
DFLD 3.4 2 
DIV 3.40 
DO 3.41 
DPAGE 3.41 
ENDDO 3.44 
FMT 3.38 
FMTEND 3.44 
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message format 
DO 3.34 
ENDDO 3.38 
LPAGE 3.33 
MFLD 3. 35 
HSG 3.32 
MSGEND 3.38 
PASSWORD 3.3U 
SEG 3.34 
definition statements, IMS/VS 
batch 7.5 
online 7. 1 3 
delete call (see DLET call) 
dependent segments 1.7 
destination parent 2.19 
device field (DFLD statement) 3.42 
device format selection, initial 3.18 
device independence 1.26 
device input format (DIE) 

associated MFS functions 3.24 
MFS statements used to create 
DEV 3.39 
DFLD 3.42 
DIV 3.40 
DPAGE 3.41 
FMT 3.38 
FMTEND 3.44 
summary 3.24 
relationship to other MFS control 
blocks 3.22 
device output format (DOF) 

associated MFS functions 3.25 
MFS statements used to create 
DEV 3.39 
DFLD 3.42 
DIV 3.40 
DPAGE 3.41 
FMT 3.38 
FMTEND 3.44 
relationship to other MFS control 
blocks 3. 22 
device page (DPAGE) 3.41 
DEV statement 3.39 
DFLD statement 3. 45 
DFS3125A, message 

application program invoking 

by an 4.30 
used for testing recovery 
procedures 8.5 
DFSBBO00 utility program 6.14 
DFSFLOT0 utility program 6.27 
DFSUCUMO utility program 6.9 
DFSUDMPO utility program 6.7 
DFSULTRO utility program 6. 18 
DFSURDBO utility program 6*12 
DFSURG10 utility program 5.15 
DFSURGLO utility program 5. 10 
DFSURGPO utility program 5.19 
DFSURGUO utility program 5.8 
DFSURPRO utility program 5.13 
DFSURRLO utility program 5.6 
DFSURULO utility program 5.4 
DFSUTR20 utility program 9.22 
DFSUTR30 utility program 9.5 
DFSVSAMP data set 7.6 1 



DIF (see device input format) 
direct access pointers 

basic data base 2.14 

logically related data base 2.25 

secondary index data base 2.28 
display area (3270 master terminal 3. 17 
distributed free space, HDAM or HIDAM 

data base 2.33, 2.84 
distribution tapes, restoring the 

IMS/VS 7.4 

NCP/VS 7.40 
DIV statement 3.40 
DL/I (Data Language/I) 1.1, 1.5 
DL/I call (see calls, DL/I batch and 

calls, DL/I online) 
DL/I call functions, batch 

checkpoint/restart calls 4.44 

delete calls 4.19 

get calls 4. 14 

insert calls 4 .20 

replace calls 4.18 
DL/I call functions, online 

change destination 4.54 

message insert call 4. 53 

message retrieve calls 4.5 2 
DL/I data base (see data base) 
DL/I interface U14 
DL/I status codes 

description (see individual call) 

detailed description of B. 1 

handling by status code error 
routine 4.11 

quick reference table A. 1 
DLET (delete) call 

basic 4. 19 

logical relationships, with 2.24, 4.38 

secondary indexes, with 4.41 
DO statement 

DFLDs 3.41 

MFLDs 3.34 
DOF (see device output format) 
DPAGE 7device page) 3.41 
DSCA= operand (DEV statement) 3.39 
dynamic attribute modification 4.57 



EJECT statement 3.45 
emergency restart 

description 3.16 

testing 8. 5 
END statement 

data base descriptor block, in 2.39 

format descriptor block, in 3.45 

program descriptor block, in 2.61 
end-of-data (EOD) 3.2 
end-of-message (EOM) 3.2 
end-of-segment (EOS) 3.2 
ENDDO statement 

DFLDs 3.44 

MFLDs 3.38 
entities, naming conventions for 1.18 
entry point to application 

programs 4.4 
erase all unprotected option (MFS) 3.39 



1.6 IMS/VS Primer 



examples (see samples, IMS/VS Primer, 
and application programs, sample) 



FEAT= operand (DEV statement) 3.39 
feature, IMS/VS DC 1.24 
fetch request element (FRE) 

defining number of 7. 23 

performance considerations 9. 16 
field format, MFS 

input message 4.55 

ouput message 4.57 
field, key 

description 1.9 

relationship to access 
path 1.9 
FIELD statement 

basic data base, for 2.37 

secondary index data base, for 2. 55 

index target data base, for 2.53 

seguence field 2.37 
file description, GSAM 2.42 
fill characters, MFS 

input message fields 3.24, 3.35 

output device fields 3.26 
FILL= operand (MFLD statement) 3.35 
FINISH statement 2.39 
fixed pages, defining in IMS/VS 

virtual control region 7.44 
floating print lines 3.29 
FLOAT parameter (DEV statement) 3.39 
FMT statement 3.38 
FMT END statement 3.44 
forced attributes (literal device 

fields) 3.42 
format 
(see also device input format, 
device output format) 
formatting 3270 messages 1.26 
format, message 

input 4.55 

output 4.57 
format set 

definition 3. 18 

IMS/VS provided format sets 3.29 
forward pointer 2.14 
forward recovery 6.21 
forward writing of log tape 7. 6 8 
FRE (see fetch reguest element) 
free space anchor point, OSAM 2.33, 2.84 
frequency of image copies and change 

accumulations 6.25, 6.32 
frequency of physical 
reorganizations 5.22 



Gantt chart, use of 1.21 
generalized sequential access method 

(see GSAM) 
get calls (data base) 

GHN 4.18 

GHO 4.18 

GN 4.15 

GO 4. 14 



get calls (data communication) 

GN 4.52 

GO 4.52 
GET HOLD NEXT (GHN) call 4.18 
GET HOLD ONIQOE (GHO) call 4. 18 
GET NEXT (GN) call 

data base segment, for a 4.15 

message segment, for a 4.52 
GET ONIQOE (GO) 

data base segment, for a 4.14 

message segment, for a 4.52 

SPA, for a 4.53 
GSAM (generalized sequential 
access method) 

checkpoint/restart, with 4.45 

DBD generation 2.42 

description 2.16 

how to use 4. 25 

PSB generation 2.59 

restrictions, online use 4.46 

SYSIN/SYSOOT, use for 4.25 
Guides, IMS/VS Primer 

Master Terminal Operators 8.2 

Remote Terminal Operator's 8.7 



HD reorganization reload utility 
(DFSORGL0) 5. 10 

HD reorganization unload utility 

(DFS0RG00) 5.8 
HDAM data base 

DBD generation 2.29 

description 2. 1 1 

design considerations 1.10 

loading 4.29 

PSB generation 2.57 

root addressable area, size of 
formula 2.84 

using 2.78 
HIDAM data base 

DBD generation 2.29 

description 2. 1 1 

design considerations 2.78 

loading 4.28 

PSB generation 2.57 

space allocation 2.83 

using 2.78 
hierarchical data structure 1.7, 2.77 
hierarchical sequence, sorting segments 

in 4.28 
HISAM, simple (see SHISAM database) 



I/O PCB 4.48 

I/O work area 4.8, 4.52 

IGNORE parameter 

DEV statement (FEAT=) 3.39 

MSG statement (SOR=) 3.32 
image copy utility (see data base image 

copy utility) 
IMS and IMSRDR procedures to SYS1.PROCLIB, 

adding 7.36, 7.78 
IMS/VS cataloged procedures 7.66 

ACBGEN 7.67 

DBDGEN 7.6 8 
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DLIBATCH 7.68 

IMS 7,71 

IMSBATCH 7.74 

IMSMSG 7.75 

IMSRDR 7.76 

PSBGEN 7-76 

SECURITY 7.77 

MFSRVC 7.77 

MFSUTL 7.78 
IMS/VS Data Base System, installing 

overview 7.4 

tasks 7. 9 
IMS/VS data sets, allocation of 

batch 7.4 

online 7.11 
IMS/VS distribution tapes 7.4, 7.11 
IMS/VS installation process 

DB system 7. 4 

DB/DC system 7. 1 1 
IMS/VS interface to application 
programs 

batch 4.2 

online 4.47 

overview 1. 14 
IMS/VS libraries 

DB system 7. 4 

DB/DC system 7.11 
IMS/VS links to OS/VS, establishing 

batch 7.2, 7.8, 7.78 

online 7.2, 7.36, 7.78 
IMS/VS system definition 
(see system definition) 
IMSCTF macro statement, IMS/VS system 

definition 7.6, 7.20 
IMSCTRL macro statement, IMS/VS system 

definition 7.6, 7.19 
IMSGEN macro statement, IMS/VS system 

definition 7.7, 7.21 
INCLUDE, use Of 2.69 
INDEX data base, primary 2.12, 2.40 
INDEX data base, secondary 2.25, 2.54 
index function, MFS, performance 

factors 9. 16 
index pointer segment, secondary 

define, how to 2.54 

description 2. 28 
INDEX reorganization reload utility 

(DFSURRLO) 5.6 
INDEX reorganization unload utility 

(DFSURULO) 5.4 
indexes, secondary 

concepts 1. 12 

define, how to 2.50 

description 2. 25 

rules for 1. 12, 2.26 

segment types use with 

pointer segment, index 1.12 
target segment, index 1.12 
source segment, index 1.12 

use, how to 2- 86 

secondary processing sequence 1. 12 
initial load program, sample U.27 
INOUT parameter 

DIV statement (TYPE=) 3.40 
input message formatting 3.24 



INPUT parameter 

DIV statement (TYPE=) 3.40 
MSG statement (TYPE=) 3.32 
input/output call (see calls, DL/I batch 

and calls, DL/I online) 
inguiry only processing 3.12 
inquiry only transaction, 

specifying on TRANSACT macro 7.26 
insert (ISRT) call 

(see ISRT call) 
installing 

IMS/VS DB system 7.4 
IMS/VS DB/DC system 7.11 
integration, application data 1.1, 2.69 
intent, data base 

conflict, potential 

scheduling 3.9, 3.12 
defined, how 3.10, 3.51 
interface to application programs, 
IMS/VS 

batch 4.2 
online 4.47 
intermediate data base, using 3.64 
intermediate text block (ITB) 3.47 
ISRT call 

basic 4.20 
loading, for 4.29 

logical relationships, with 2.24, 4.3I 
message segment, for a 4.53 
secondary indexes, with U.U1 
SPA, for a 4.66 
ITB (intermediate text block) 3.47 
iterative processing (MFLD/DFLD) 
DO statement 
DFLD 3.41 
MFLD 3.34 
ENDDO statement 
DFLD 3.44 
MFLD 3.38 



JCL, sample 

installation, for 
batch 7.9 
online 7.4 1 
exercising, for 7.U8 
(see also Chapter 2, Sample Job 
Listing in the IMS/VS Primer 
Sample Listings manual) 
justification, B FS field 3.24, 3.26 
JUST= operand (MFLD statement) 3.35 



key, data base root 1.9 

L parameter (MFLD statement) 3.35 

LCHILD statement 

basic HIDAM data base, for 2.38 
index target data base, for 2.51 
logical related data base, for 2.45 
primary index data base, for 2.38 
secondary index data base, for 2.55 



1.8 IMS/VS Primer 



length 

data base fields 2.37 
device fields 3.26 r 3.42 
message fields 4.56 
print lines, 3270 3.29, 3.42 
libraries, IMS/VS (see IMS/VS 

libraries) 
limiting access to data 1.14, 2.57, 3.49 
line groups, terminal 7.31 
LINE macro statement, IMS/VS system 

definition 7.32 
LINEGRP macro statement, IMS/VS 

system definition 7.31 
lines per printed page 3.29 
link security (see security 

maintenance utility) 
linkages, MFS control block 
chained 3.20 
LPAGE/DPAGE 3.22 
message descriptions 3.23 
message fields and device fields 3.22 
linking IMS/VS to OS/VS 

IMS and IMSEDR procedures, making 

accessible to OS/VS 7.9, 7.36, 7.78 
link-editing modules into LPALIB 
abend formatting routine 7.78 
resource clean-up module 7.78 
link-editing type 2 SVC in 
OS/VS nucleus 7.8, 7.37, 7.78 
literal fields 

input message 3.24 
output message 3.26 
performance factors 3.60 
system literals 3. 35 
literal length (MFS) 3.35 
load, initial data base 
basic data base, a 
HDAM 4.29 
HIDAM 4.28 
SHISAM 4.29 
sort, use of 4.28 
flowchart 4.26 
logical relationships, a data 

base with 4. 38 
overview 4.26 
planning for 1. 21 
secondary indexes, a data base 

base with 4.41 
sample program and jobs 4.27 
log, IMS/VS system 

accounting, use for 9.20 
administration of 6.31 
modifications, recording data 

base 6.5 
power failure, closing after a 6.27 
purpose of 3.15, 6.5 
restart, for system 3.22 
recovery, use in 6.22 
recovery of 6.18 
retention periods for 6.26 
serial numbers 6.32 
statistics, retrieving from 9.19 
termination of 6.27 
write ahead option 7.60 



log recovery utility program, system 

(DFSULTE0) 6. 18 
log tape, IMS/VS (see log, IMS/VS system) 
log tape administration 6.31 
log tape data set names 6.31 
log tape retention periods 6.26 
log tape write ahead 7.60 
log terminator utility program, system 

(DFSFLOT0) 6.27 
logical child 

concept 1. 10, 2. 17 

define, how to 2.44 

deleting 2.24, 4.38 

inserting 2.24, 4.38 

relationship to 

physical parent 1. 10, 2.17 
logical parent 1.10, 2.17 

use of 2.8 5 
logical data base 

concept 1. 10, 2. 19 

define, how to 2.47 

relationship to physical 
data base 1. 10 

use of 2.85 
logical data base reorganization 

description 5.3, 5.26 

flow chart 5-24 

performance considerations 5.25 

restructure limitations 5.27 

utilities for 5.2 
logical page (LPAGE) , MFS 3.33 
logical paging, operator 3.27 
logical parent 

concept 1.10 

define, how to 2.45 

deleting 4.38 

inserting 4.38 

relationship to logical 
child 1. 10 

replacing 4.37 
logical parent pointer 2.25 
logical relationships 

building 2. 19 

concepts and definition 1. 10 

description of 2.19 

paths, access 1.10 

pointers used with 1.10, 2.25 

restructuring 5« 27 

segment types involved with 1.10 

utilities used for 5. 2 
logical relationship resolution utility 
programs 

data base prefix resolution 5.15 

data base prefix update 5.19 

data base prereorganizat ion 5.13 
logical terminals 

concept, definition of 1.27 

relationship to physical 
terminal 1.27 

naming conventions for 7.30, 7.35 
tic clearogical page] 3.33 
LPAGE/DPAGE relationships 3.22 
LTEFM (see also logical terminal) 

access by application 
program 4.49 



Index 



1.9 



concept, IMS/VS 1.27 
relationship to node, 
physical terminal, and 
end user 1. 25 
LTH= operand 

DFLD statement 3.42 
MFLD statement 3.35 
LTNAME parameter (MFLD statement) 3.35 



MACLIB, required OS/VS option 7.10 
macro statements, IMS/VS DB system 
definition 
INSCTF 7.6 
IMSCTRL 7.6 
I MS GEN 7.7 

resource naming rules 7.16 
macro statements, IMS/VS DB/DC system 
definition 

data base and application 
&PPLCTN 7.25 
DATABASE 7.24 
TRANSACT 7.26 
data communication-BTAM 
COMM 7.31 
CTLUNIT 7.32 
LINE 7.32 
LINEGRP 7.31 
NAME 7,35 
TERMINAL 7.33 
data communication-VTAM 
COMM 7. 27 
NAME 7.30 
TERMINAL 7.29 
TYPE 7. 28 
environment 

BUFPOOLS 7.23 
IMSCTF 7.20 
IMSCTRL 7.19 
IMSGEN 7.21 
MSGQ0E0E 7.23 
SPAREA 7.23 
resource naming rules 7.16 
macro statements, maximum occurrences 

system definition 7. 16 
masks, PCB 
batch 4.5 
online 4.49 
master terminal 

commands overview and operating 
procedures (see IMS/VS Primer 
MTO's Guidef 
description 1.27, 3.17 
devices used for 3.17 
format, screen 3. 17 
operator 8.2 

operator procedures, maintaining 8.5 
OS/VS console, relationship to 3. 18 
system definition of 7.30, 7.35 
message 

definition 3.2 
editing of 3.24, 3.26 
types of 3.7 
message area (3270 master terminal) 3.17 
message field (MFLD) 3.35 



message format 

input 3.7, 4.55 
output 3.7, 3.14, 4.56 
performance factors 3.60 
message format service 

control statements overview 3.30 
description 3.18 
design considerations 3.59 
overview 3.18 
message input descriptor (MID) 

associated MFS functions 3. 18 
MFS statements used to create 
DO 3.34 
ENDDO 3.38 
LPAGE 3.33 
MFLD 3.36 
MSG 3.32 
MSGEND 3.38 
PASSWORD 3.34 
SEG 3.34 
relationship to other MFS control 
blocks 3. 20 
message input header 4.55 
message output descriptor (MOD) 
associated MFS functions 3.18 
MFS statements used to create 
DO 3.34 
ENDDO 3.38 
LPAGE 3.33 
MFLD 3.35 
MSG 3.32 
MSGEND 3.38 
PASSWORD 3.34 
SEG 3.34 
relationship to other MFS control 
blocks 3. 20 
message output header 4.56 
message prefix 
input 4.55 
output 4.56 
SPA 4.64 
message processing region (MPP) 3.5 
message queues 

description 3.7 
data sets 7.13 
recovery 3.15, 3.16 
message scheduling 3.3 
message segment 

description 3.2 
format 

input message 4.55 
output message 4.56 
scratch pad area (SPA) 4.64 
Message/Format Language Utility Program 

(see MFS language utility program) 
MFLD~statement 3.35 
MFS (see message format service) 
MFS language utility program 
control statements 
compilation 3.44 
definition 3.32 
naming conventions 3.31 
overview 3.30 
example 3.42 
execution 3.47 
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JCL 3.49 
procedures 

MFSRVC 7.77 
MFSUTL 7.78 
syntax 3.31 
MFS service utility program 3.49 
MFSUTL procedure 7.78 
HID (§ee message input descriptor) 
migration, DB to DB/DC 7.78 
MOD (see message output descriptor) 
MOD parameter (DFLD statement) 3.42 
modifications, data base logging 

of (see log, IMS/VS system) 
monitor 

EB system (see DB Monitor, 

IMS/VS) 
DB/DC system (see DC Monitor, 
IMS/VS) 
monitoring online performance 9.14 
MSG statement, MFS 3.32 
MSGEND statement 3.38 
MSGQUEUE macro statement, IMS/VS 

system definition 7.23 
multipage output message 3.27, 4.58 
multiple message mode 3.7 
multiple positioning in data 

base 4. 24 
multipoint line, definition, IMS/VS 7.31 
multisegment message 3.27, 4.58 



NAME macro statement, IMS/VS system 

definition 7.30, 7.35 
names, logical terminal 7.30, 7.35 
naming conventions 

entities 1.18 

formats, MFS 3.31 

jobs, sample 1.19 

log tape data set 6.31 

logical terminals 7.30, 7.35 
naming rules, IMS/VS system definition 

resource 7. 16 
NCP/VS (Network Control Program /VS) 

generation 7.39 

introduction 1.24, 1.26 
network (see communications network) 
Network control Program/VS (see NCP/VS) 
network design 3.38, 9.31 
node, VTAM 1.25 

NODISP parameter (DFLD statement) 3.42 
non-update processing 

batch 4.14 

online 3. 12, 4.60, 4.62 
NOPFOT parameter (DFLD statement) 3.42 
normal restart, IMS/VS 3.16 
nucleus, OS/VS, 

linking 7.8, 7.37, 7.78 
null characters (for MFS) 

COBOL, coding in 4.60 

PL/I, coding in 4.62 

use for 4.57 



null fill 

input message fields 
description 3.24 
FILL= operand (MFLD) 3.35 
output device fields 3.26, 3.42 
NULL parameter, MFS 

MFLD statement (FILL=) 3.35 
NXT= operand 

LPAGE statement 3.33 



online buffer pools, optimizing 

optimizing 9.14, 9.23 
operating system, 

preparing for IMS/VS 7.2, 7.78 
operator, IMS/VS master 

terminal 1.27, 8.2 
operator, remote terminal 8.6 
operator logical paging 3.27 
optimization of 

application programs 9.13 
data communication design 9.30 
IMS/VS online system 9.13 
physical DB implementation 9. 12 
VTAM storage pool parameters 9.27 
organization of data, IMS/VS (see 

data base) 
OS/VS data files, use of 

(see GSAM) 
OS/VS libraries, cataloging for 

IMS/VS system definition 7.4, 7.38 
OS/VS links to IMS/VS, 

establishing 7.2, 7.78 
OS/VS programs used with IMS/VS 7.4 
OS/VS supervisor call routine 

required by IMS/VS 7.3 
OS/VS system modification program 

(SMP) 7.81 
OS/VS 1 consideration 7.2 
OS/VS2 (MVS) considerations 7.78 
OSAM (overflow sequential access 

method) 2. 10 
output call, DL/I (see calls, 

DL/I batch and calls7 DL/I online) 
output device field attributes 3.28 
output limits, application program 7.26 
ouput message default format 4.56 
output message paging 3. 27 
output to alternate destination 
alternate PCB 3.50 
CHNG call, use of 4.54 
overflow sequential access method 

(OSAM) 2. 10 



PA (program access) keys (3270) 

PA1 3.28 

PA2 3.28 

PA3 3.18 
PAGE= operand 

DEV statement 3.39 

MSG statement 3.32 
paging, operator logical paging 3.27 
paging, output message 3.27 
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password and/or terminal 
security, IMS/VS 

description 1.29, 7.64 
definition utility 7.64 
definition, MFS 3.34 
PASSWORD statement, MFS 3.34 
position in master terminal 
format 3. 17 
PASSWORD statement, MFS 3.34 
path calls 4.21 
path, hierarchical 1-9 
PCB (program communication block) 
defining 

alternate destination 3.50 
batch 2.58 
online 3.50 
application program use 

alternate destination 4.48 
batch 4.5 
online 4.48 
PCB statement 

alternate destination 3.50 
basic data ba_.a, for 2.58 
GSAM data base, for 2.95 
logical data base, for 2.59 
secondary index data base, for 2.62 
PCB mask (data base) 4.5 
PCB mask (data communication) 4.4 9 
performance considerations 

(see Chapter 7, Optimization) 
PERT chart, sample 

DB system, for 1. 21 
DB/DC system, for 1.35 
PFK12 (program function key 12) for 

3270 remote copy 3. 18 
phases, Primer sample 
introduction 1.4 
jobs 

phase 7.49 
phase 1 7.49 
phase 2 7.52 
phase 3 7.54 
phase 4 7.551 
physical child 
concept 1.7 
define, how to 2.29 
pointers use with 2.14 
physical data base 

concepts, definition 1.5 
relationship to logical 

data base 1.10 
define, how to 2.29 
types, subset 2. 5 
rules for defining logical 
relationships in 2.22 
physical data base reorganization 

(see data base reorganization) 
physical data base recovery (see 

data base recovery) 
physical terminal 1.26 
physical/logical terminal 
relationship 1.27 



physical parent 

concept, definition 1.7 
define, how to 2.29 
pointers used with 2.14 
physical twin 

concept, definition 1.7 
pointers used with 2.14 
PL/I Optimizer, conventions and use of 
batch program structure 

call formats (see individual calls) 
guidelines 4.34, 7.37 
IMS/VS interface 4.4-4.11 
CAUTION for multi-tasking during 

link-editing 4.35, 7.37 
online program structure 

call formats (see individual calls) 
conversational MPP 4.70 
guidelines 4.60, 4.68 
IMS/VS interface 4.50 
inquiry MPP 4.62 
pointers, data base 
basic 2. 14 

logical relationships, with 2.25 
secondary indexing, with 2.28 
pools, IMS/VS buffer (see 

buffer pools, IMS/VS) 
pools, VTAM storage (see VTAM) 
POS= operand (DFLD statement) 3-42 
positioning, data base, after 

DL/I call 4. 23 
prefix resolution utility (see data base 

prefix resolution utility) 
prefix, segment 3.2 
prefix, SPA 4.64 
prefix update utility (see data base 

prefix update utility) 
preparing for IMS/VS use 

NCP/VS 7.39 

operating system 7.2, 7.78 
VTAM 7.38 
prereorganizat ion utility (see data base 

prereorganization utility) 
prerequisite publications v 
primary index (HIDAM) 2.12 
primary master terminal 
description 3.17 
specifying 7.30, 7.35 
Primer function, IMS/VS 
concept iii 

overview and limitations, 
subset 1.35 
print lines/page (3270) 3.29 
PRINT statement, MFS 3.45 
printed page format control 3.29 
problem reporting, IMS/VS online 
system 8.8 

procedures, IMS/VS cataloged 
description 7.66 
listings 7.67 
procedures, data base 

recovery 6.20 
procedures, data base 
reorganization 5.20 
procedures, IMS/VS 
operating 8.1 
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processing intent, application 

program 2.58, 3.10, 3.51 
processing limits 

message scheduling 3.8, 7.26 
ouput messages, number and size 
of 7.26 
processing regions, types of 3.3 
processing sequence, secondary 1.12 
program access (PA) keys 
PA1 3.28 
PA2 3.2 8 
PA3 3.18 
program communication block 

(see PCB) 
program function key 12 (PFK12) 3.18 
program isolation (PI) 3. 12 
program specification block 

(see PSB) 
Program Specification Block Generation 
(PSBGEN) 
batch 2.57 
online 3.49 

procedure, cataloged 7.76 
programming languages 
use with IMS/VS 4.2 
programs, application (see 

application programs) 
project approach 1-19 
project plan, sample 
DB system, for 1.21 
DB/DC system, for 1.35 
PROT parameter (DFLD statement) 3.42 
PSB (program specification block) 
concept and definition 1.14 
generation 
batch 2.57 
online 3.49 
PSBGEN procedure 7.76 
PSBGEN statement 

basic data base, for 2.60 
logical data base, for 2.62 
secondary index data base, for 2.63 



qualified SSAs 4. 10 

queues, message 

allocation 7. 1 3 
description 3.7 
recovery 3-15, 3.16 



E parameter (MFLD statement) 3.35 

randomizing algorithm 
description 7.57 
HDAM, use of 2.12, 2.79 
how to write 7.58 
IMS/VS-supplied module 7.58 
sort exit, use in 4.29 
simple sequential, a 7. 59 
specification in DBD 2.31 

record, data base 

definition of 2.6 

recovery, data base (see data base 
recovery) 



recovery utility (see data base recovery 

utility) 
regions, types of 3.3 
relationships 
logical 1.10 

MFS control blocks, between 3.20 
parent/child 1.7 
reorganization, data base (see 

data base reorganization) 
reorganization utilities 5.3 
repetitive generation of 
DFLDs/MFLDs 3.34, 3.4 1 
KEPL call 

basic 4.18 

logical relationship, 

with 2.24, 4.37 
secondary indexes, 
with 4.40 
replace call (see REPL call) 
requirements, gathering data 

base 2.69 
resource clean-up module (DFSMRCL0) , 

IHS/VS, including in OS/VS2(MVS) 3.49 
resource naming rules, IMS/VS system 

definition 7. 16 
response alternate PCB 3.50, 4.35 
response time 

design considerations 3.55, 9.30 
estimating, simple technique 9.31 
restart, IMS/VS 
emergency 3.16 
normal 3. 16 
retention periods, log tapes and 

image copies 6.26 
review, design 2.87 
root segment 1.9, 2.6 



sample application, IMS/VS 1.2 

(see also samples, IMS/VS Primer) 
samples, IMS/VS Primer 

application environment 1.2 
batch programs 

Assembler 4.27 
COBOL and PL/I 
phase 1 4.32 
phase 2 4.39 
phase 3 4.41 
data base 

Parts 2.2 

Customer Orders 2.3 
Customer Name 2. 4 
data base load procedures 5. 23 
data base recovery procedures 6.20 
data base reorganization 

procedures 5.26 
DB system definition 7.5 
DB/DC system definition 7.13 
DBDs, basic 2-40 

DBDs, logical relationships 2.46, 2.49 
DBDs, secondary indexes 2.56 
distribution 7.5, 7.12 
formats, MFS 3-46 
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jobs 

phase 7.49 
phase 1 7.49 
phase 2 7.52 
phase 3 7.54 
phase 4 7.55 
listings (see IMS/VS Primer 

Sample Listings) 
online programs 4.60, U.70 
overview 1.2 
PSBs, basic 2.61 
PSBs, logical relationships 2.62 
PSBs, secondary indexes 2,63 
PSBs, online 3.51 
transaction/data element 
matrixes 2. 70 
scheduling, IMS/VS message 3.8 
scratch pad area (SPA) 

description 3. 14, 4. 64 
definition 1.29 
design considerations 3.57 
defining at IMS/VS systea 

definition 7.23, 7.26 
layout and use 4.65 
screen formatting, 3270 display 3.18 
secondary indexing 2.25 
secondary master terminal, IMS/VS 3.17 
security 

establishing 7.64 

overview 1.29 

terminal commands, authorizing 

use of 7.65 
transactions, restricting entry 
of 7.65 
security maintenance utility, 

IMS/VS 7.64 
security violation attempts, recording 

of 7.27, 7.31 
SEGM statement 

basic data base, for 2.35 
logical data base, for 2.48 
logical relationship in physical 
data base, for 

real logical child, for 2.44 
virtual logical child, for 2.45 
secondary index data base, for 2.54 
segment 

data base 1. 6 
message 3.7 
segment format 
data base 2.7 
message 

input 3.7 
output 3. 14 
scratch pad (SPA) 4.64 
segment search arguments (SSAs) 
characteristics 4.11 
command codes for 4.11 
concept and function of 4.9 
qualification of 4.10 
structure of 4.9 
segments, data base 
data portion 2.7 
defining 2.35 
definition 1.6 



fields 1.16 

formats 2.7 

length 2.7 

prefix 2.7 

relationship to data base 

record 1.6 
types 

basic 1.9 

logical relationships, with 1.10 
secondary indexing, with 1. 12 
segments, sorting in hierarchical 

sequence 4.28 
SENS EG statement 2.59, 3.51 
session, relationship to 

end users and nodes 1.25 
sequence fields and access paths 1.9 
sequence, secondary processing 1. 12 
SHISAM data base 

define, how to 2.29 
description 2.15 
using 2.85 
sibling segments 1.9 

simple HIS AM data base (see SHISAM data 
base) 

SMP (see system modification program) 
SNA (see system network architecture) 
sort exit routine, E61 

used during data base load 4.29 
sort work files, allocating 
during reorganization 5.25 
sort/merge program required 7.4 
sorting segments in hierarchical 

sequence 4.28 
SPA (see scratch pad area) 
space allocation 

data base data sets, for 2.83 
IMS/VS data sets, for 7.9, 7.41 
SPAREA macro statement, IMS/VS system 
definition 7.23 
SSA (see segment search arguments) 
Stage 1", IMS/VS system definition 
DB 7.5 
DB/DC 7.13 

ordering of input deck 7.35 
Stage 2, IMS/VS system definition 
DB 7.10 

DB/DC 7.36, 7.44 
STAT call 4.2 5 

statistical analysis utility 9.19 
statistics 

data base buffer pool 

produced b y DB Monitor 9-3 
produced by STAT call «.25, 9.1 
produced by /DIS POOL 
ALL command 9.14 
DB monitor 9.4 
DC monitor 9.21 
log tape 9.19 
online buffer pools 9. 14 
status code, returned after DL/I 
calls 

use of, program 4.11 
types 4.11 
table of A. 1 
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list of B.1 

overview 4. 1 1 
steps with IMS/VS installation 

DB 7.4 

DB/DC 7.11 
storage pool trace, VTAH 9.27 
subpool definition statement, for 
defining size and number of buffers 

OSAM 7.62 

VSAM 7.61 
subsequence field, secondary 

index 2.28 
subset, IMS/VS Primer 

concept iii 

overview and limitations 1. 35 
SOF= operand (DO statement) 

DFLDs 3. 41 

MFLDs 3.34 
SVC, OS/VS 

IMS/VS use Of 7.3 
SVCTABLE, required OS/VS option 7.3 
syntax conventions 

EBDs and PSBs, for 2. 30 

formats, for 3.31 

IMS/VS system definition 7.5 
SYSMSG= operand (LEV statement) 3.39 
SYSPRINT listing control, MFS 

EJECT statement 3.45 

PRINT statement 3. 45 

SPACE statement 3.45 

TITLE statement 3.447 
system console, OS/VS, as 

IMS/VS master terminal 3. 18 
system definition 

IMS/VS 

batch 7.5 
online 7.13 

NCP/VS 7. 39 

VTAM 7.38 

OS/VS2 (MVS) considerations 7.1 

Stage 1 7.5, 7.13 

Stage 2 7.10, 7.36, 7.44 
system literals (MELD statement) 3.35 
system message field (3270 display 
devices) 

description 3.29 

SYSMSG= operand 3.39 
system modification program (SMP) , 

OS/VS 7.81 
system network architecture 

basic concepts 1.24 

relationship to IMS/VS 1.24 

VTAMs role in 1.26 
system service calls (see calls, IMS/VS 

system service) 
System/370 console, IMS/vs 
provided support 3.18 



tapes, IMS/VS distribution 7.4 
telecommunication (s.ee communications 

network) 
terminal commands, authorizing use 

of 7.65 
terminal configuration supported 1.26 



TERMINAL macro statement, IMS/VS 

system definition 7.29, 7.33 
terminal, master (see master terminal) 
terminal response node 1.30 
terminal security 1.29, 7.65 
terminals 
defining 

IMS/VS, to 7. 30 
NCP/VS, to 7.40 
VTAM, to 7.38 
logical 1.27 
physical 1.26 

relationship to VTAM node 1.25 
terminating an application program 4.11 
testing 

batch programs 4.30 
online programs 4.30, 4,70 
MTO procedures 8.5 
TIME parameter (MFLD statement) 3.34 
TITLE statement, MFS 3.44 
training terminal operators 8.6 
transaction 

application program, relation 

to 2.69 
data elements, relationship 

to 2.67 
define, at system definition 7.26 
definition 2.66 
design considerations 
batch 2.67, 9.10 
online 3.54, 9.30 
message, relationship to 3.2, 3.54 
processing flow, message 3.3 
transaction codes, restricting entry 

of 7.65 
transaction/data element matrix 
concepts and definition 2.67 
gathering requirements 2.69 
samples 2.70 
truncation, MFS literal 

filed 3.35 
TYPE macro statement, IMS/VS 

system definition 7.28 
TYPE= operand 

DEV statement 3.39 
DIV statement 3.40 
MSG statement 3.32 



user input area, master terminal 3. 17 

user liason 8.6 

utility programs, IMS/VS 

data base loading, for 5. 2 
data base recovery, for 6.5 
data base reorganization, 

for 5.2 
data base optimization 9.5, 9.22 
log tape recovery 6.18 
log tape statistics 9. 19 
log tape termination 6.27 
DB Monitor report print 9.5 
DC Monitor report print 9.22 
overview 

batch 1. 15 
online 1.32 
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view on data, program (sge masks, 

PCB) 
virtual child 

concept and definition 2.17 
define, how to 2.45 
virtual control region, IMS/VS, 

defining fixed pages in 7.37 
virtually paired bidirectional 
logical relationship 
discussion of 2. 17 
use of 2.85 
VSAM (virtual storage access method) 
catalog recovery 

considerations 6.26 
data space allocation, data 
base 2.85 

IMS/VS buffer pools 7.59 
subpool definition, IMS/VS 
buffer 7. 61 
VTAM (virtual telecommunication access 
method) 

description 1. 26 
installation 7.38 
library creation 7.38 
main storage pools 
adjusting 9.29 
definition 7.38 
tracing 9.27 
operation considerations 8.8 
relationship to IMS/VS 1.24 



start options 7.38 
storage pool trace 9.27 
system definition, related 
IMS/VS macros 7.27 



write ahead option, log tape 7.60 
write -to -opera tor -with -reply (WTOR) 
backup master terminal, as 3.18 
message DFS3125A, used for 
test 4.30, 8.5 



XFST call 

batch, for 4.4 2 

BMP, for 4.47 

GSAM considerations 4.45 



3270 Information Display System 
clear key, impact of 3.4 1 
copy function 

candidate printers 7.30, 7.35 

invoking of 3.18 
program access (PA) keys 3.18, 3.28 
program function keys 12 

(PFK12) 3.18 
master terminal support 3. 17 
message format service (MFS) 3.18 
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